Mentoring on MoskitoHero

Ruby Best Practices - Method Arguments

Fri, 12 Jan 2024 00:00:00 +0000

To write readable and maintainable code, follow a few simple rules about argument ordering.

Tip 1: Optional arguments go last

When a method takes several arguments, and some of them have default values, make sure to put the optional ones at the end. Take this method definition:

def foo(a, b = "val_b", c)
  # some code...
end

Looks fine at first glance. But in practice, it’s impossible to call this method with values for a and c without also specifying b. You end up writing:

foo("val_a", "val_b", "val_c")

…which defeats the purpose of setting a default for b if you’re forced to specify it every time. ¯(ツ)/¯

Solution: move optional arguments to the end

def foo(a, c, b = "val_b")
  # some code...
end

Now you can call:

foo("val_a", "val_c")

No problem 😎.

Tip 2: Use keyword arguments (aka kwargs)

Tip 1 only gets you so far. What if you have multiple optional arguments and want to override just the last one? You’d still need to specify all the previous ones. For example:

def foo(a, b, c = "val_c", d = "val_d", e = "val_e")
  # some code...
end

Want to change only e? Too bad — you still have to write:

foo("val_a", "val_b", "val_c", "val_d", "my_val_e")

Now imagine this in a large codebase:

foo(user.id, "DONE", true, false, 1, "always", true, post.id)

And you’re left thinking: "Wait, what’s that false again? What does the 1 do? Why 'always'?" Not ideal, especially under pressure in a production bug fix.

Solution: switch to keyword arguments when you hit 2+ optional params

Benefits:

Argument order doesn’t matter anymore
You can ignore defaults entirely

The method now becomes:

def foo(a, b, c: "val_c", d: "val_d", e: "val_e")
  # some code...
end

To change only e, you write:

foo("val_a", "val_b", e: "my_val_e")

Ninja-level tip — the clean coder’s take:

If your method takes more than 1 argument, make everything after the first a keyword argument. Always.

Example:

def send_message_to(recipient, confirm: true, bcc: "joe@bill.com", cc: "jane@doe.com")
  # ruby code
end

Here, the first argument is obvious thanks to the method name: you’re sending a message to someone. Called without options:

send_message_to("sam@sam.com")

Clear and concise. Compare a non-keyword version:

send_message("recipient@mail.com", false, "joe@bill.com", "paul@smith.com")

…with the keyword version:

send_message_to("sam@sam.com", bcc: "paul@smith.com", confirm: false)

If you adopt these habits, future you will thank you when you revisit the code to debug or tack on yet another parameter.

Love your error messages as thyself

Tue, 17 May 2022 07:44:36 +0000

Learn to hate, then love error messages.

Stack Overflow overflow

I have lost so much time on Stack Overflow.

I mean Stack Overflow is great, and software development knowledge would not be so advanced and so widespread without its great influence. What I mean is that I have often found myself repeating the endless pattern of 'Hey, I have an error… Wow, so many words… Let’s google this. Stack Overflow has it! Let’s see what they say'

I am not talking about the infamous Stack Overflow copy-paste syndrome, nor am I dismissing the great answers produced by the great developers out ther, but rather about the missing step in the example above: making sense of the error message myself before actually looking for a ready-made answer.

Our brain is so quick at taking shortcuts that it often makes us lazy and skip the seemingly unneeded steps our thinking needs to fully develop. Take the example of walking. Although I don’t exactly remember taking my first step in this world, I can imagine it was a movement that required so much concentration - not to say bravery - and coordination that it must have felt quite awkward at the beginning. Today, I don’t even think about it. My brain just orchestrates everything, allowing me to go for a walk and actually think about something else.

Think about the first day you typed your first computer program. Think about the way you were thinking at the time. Maybe you are currently learning computer science and many mechanisms experienced developers don’t even think about are steps you consciously take, one by one, in order to reach code quality - or even to write code that actually works.

And while learning, we all encountered bugs. The language we were coding in was talking to us with complicated words, and concepts we sometimes did not even know about. We all googled for solutions. And Stack Overflow is so well conceived and maintained that we most certainly found the answer there. And it happened again. Error messages were so hard to understand, so cryptic, sometimes. So we just kept copy-pasting the error messages, and it just kept throwing correct answers at you, which, with a little adaptation, just worked.

And then, your brain skipped the error-message-reading step.

But we don’t want to just be very, very, very talented googlers, do we?

RTFEM!

Read the f***ing error messages!

So I encourage all of you learners to actually take a long look at the error messages that are thrown right in your face just as you were expecting a successful compilation. Take the time to read them. Take the time to look at those weird symbols that show up here and there. And you know what? You may not get to the point quicker at first, but you will gain a deeper knowledge of how your language is actually built, how it works internally. You might look at your fellow programmers increase their skills faster on the surface, but your understanding of error messages will eventually turn you into a Code Jedi Master.

What made me really stop overlooking error messages was reading Ruby Under A Microscope by Pat Shaughnessy, a most excellent book about the way Ruby is actually written in C, the way the language parser works and the way it turns the words you write into machine-understandable concepts.

Somewhere in the first part of the book that introduces how the parser works, the author talks about language tokenisation, which is - very basically - how the parser takes words and understand how to match them with a feature. And here they were, in a code example, my long-seen-yet-so-little-known error message friends, namely tSTRING, tCONSTANT and tINTEGER.

If only I had known what these correspond to before, error messages such as these would never have had me google for an answer.

But how could I know? When you google for ruby tString, you get all sorts of results, mostly skipping the preceding t. In order to get to the real stuff, I should have taken the time to actually read the error messages and wonder:

What is the language trying to tell me?

And if that sounds awkward, just remember that your programming language is actually a computer program written by other humans, and ask yourself:

What is the author of the language telling me to look at?

Chances are he is trying to get you to look at features of the language that may not be plain to see, but a little hidden from sight. And if he is trying to have you look at these, you might just as well do it. And learn.

Learn to love your error messages

Not only should you read error messages carefully, but you should also take the time to craft yours with love and care. Like I said in an earlier post, you should always try to write code with your future self in mind. And I guess the same applies to error messages.

Don’t just raise Error, or StandardError in your lib. Actually write your own OddError class. Give it a message. Make it clear. Make it so your user - and that may be the future you - is eager to look at what you coded and understand how it is architectured.

An error message must be clear, so it requires your code to be clear, and therefore it requires your programming mind to be clear about what the code is actually doing. Error messages tell something about your self.

Error messages are the conversation between the author of a program and his users. As a programmer, you will be either one or the other, in turn, and often both at the same time.

Error messages will make you grow while learning software. They will make you grow while using software. They will make you grow while writing software. Do not just dismiss them and skip to the Stack Overflow step.