There's a great little trick you can do to improve the readability of your code. A common problem is dealing with methods that have a boolean flag arguments. Here's an example I ran into just today in a Rails application:
def rating_stars(..., clickable = false)
The problem with this is that you typically see calls like this scattered around the application:
<%= rating_stars(..., true) %>
Would you know what
true did there if I hadn't shown you the name of the variable first? I didn't. I had to go hunting for that method definition.
Ironically the opposite problem, a magical dangling
false, is much more rare in my experience. That's typically the default for these kind of arguments and it just makes more sense and reads better to leave it out.
Anyway, the point is that we can typically improve the ease of understanding the common case. Remember that in Ruby
nil are false while everything else is true. That means that truth is very loosely defined and we can pass a lot of things for our boolean flag value. For example, after looking up the method and understanding what was needed, I chose to call it like this:
<%= rating_stars(..., :clickable) %>
My hope is that might save a future maintainer a trip to the method definition to understand the call.
I've used that trick in quite a few situations now. To give another example,
FasterCSV's documentation encourages user code to pass
:headers => :first_row instead of just
:headers => true. That has the advantage of being more self-documenting as well as leaving me room for possible expansion to the API.