I had a lot of fun writing about the Boolean trap issue. I also have more similar API-related discussions in the pipeline. Rather than writing a long-ish essay again, I decide to put out more bite-size chunks. Here is the first.
Careful when choosing the name of an object property!
Let’s say you create a date picker component, something like depicted in the following screenshot:
To set the range of the year where the user is allowed to choose a certain date, here is a bad examples of the property names:
picker.yearFrom = 1900;
picker.yearTo = 2100;
It’s quite “conversational” to decide the names like yearFrom and yearTo. A much better choice would be like this:
picker.minimumYear = 1900;
picker.maximumYear = 2100;
You could use other idioms, like start and end, if you like. The philosophy is the same, when you define a property, try to say it loud in a normal English sentence.
Here is another example. Say you want to introduce yourself:
“Hi. Call me Adam.”
Does that mean you are going to write code like this?
person.callMe = 'Adam';
Obviously not. Imagine your introduction has been changed to:
“Hi. My name is Adam.”
which is analog to the following:
person.name = 'Adam';
as if you say it (loud):
The name of the person is Adam.
Let’s for the moment assume that this introduction happens in an airport, as you exchange greetings with fellow passengers in the waiting room. The conversation continues:
“My flight is from SFO to JFK.”
Let’s write the code for that. Maybe these lines?
flight.from = 'SFO';
flight.to = 'JFK';
Again, it’s very conversational. Technically no grammar is violated is your original sentence, though imagine if it would have been rewritten as:
flight.departure = 'SFO';
flight.destination = 'JFK';
Less ambiguous? I bet!
In many cases, it’s impossible to choose one-word property name. In fact, it’s better to avoid it if that may cause some confusion.
If you have a scrolling list, where the user can swipe his finger horizontally or vertically, one way to specify it is:
X.scroll = 'horizontal';
Y.scroll = 'vertical';
Still considering the original observation that:
the code is usually written once but read many times.
those two lines lead to an ambiguity because scroll as a word can mean a lot. At least, it’s a verb and also a noun (though the latter often connects to the magical world). What you really want people to understand is perhaps:
X.scrollDirection = 'horizontal';
Y.scrollDirection = 'vertical';
Say it loud and it makes sense:
The scroll direction of X is horizontal.
I hope you get the idea. See you in the next installment!