artisanal bytes

“Hand-crafted in San Francisco from locally sourced bits.”

On The Importance Of The Semicolon

The semicolon itself is not truly important, nor is the semicolon often the subject of code formatting arguments. All developers know where they go, but many of today’s developers just hate having to use them at all. Me, I’m not offended by the requirement of a semicolon at the end of my statements. But I’m old school.

The true subject of importance is code formatting. I have been known in the past to be adamant about the placement of braces, but I don’t much care anymore. What I do care about is that all of the braces in a project are placed using the same rules. And of course, that rule extends to the formatting of an entire project: it should all look the exact same; I should not be able to tell who coded up one file based on the different formatting that it uses. We must do everything we can to make digesting a code base easy for new developers, but also for ourselves when we come back and try to decipher what seemed so sensible months earlier. Having a code base that looks the same is a seemingly minor move toward that ideal, but it is a very important one.

I have had a few occurrences recently that have put the topic at the front of my mind.

An engineer who I had worked with previously started at Opower recently, and as I was going through one of his code reviews, I felt a little bad as I called out style mistakes. Derrick is an exceptional engineer, with many years of experience, and I trust the code he writes and the design decisions he makes. Telling him to put a space between if and an opening parenthesis felt trite1. But if he doesn’t pick up the habits of the styles that we use as soon as he starts writing code for us, then he likely will drift off into his own style for good, causing more divergence in our code. Also, another senior engineer on the team was littering the code review with style comments as well, so I didn’t feel so bad.

I have contributed a few patches to the Kiji Project, and on one of the earlier ones, which happened to be a fairly large patch, I received a lot of style comments on the code review that Christophe and Aaron oversaw. As the comments rolled in, I felt a little dismayed that I had made so many style mistakes, given that I had read the style guide, but I was also happy to see them taking so much pride in their code base. In fact, I was downright enthused.

In both of these experiences, I noticed that Brett and the guys from WibiData prefixed their style comments with “nit” or “nitpick.” When I made style comments, I just made them: “A space goes between the if and the opening parenthesis.” That seems dead obvious to me that it is a nitpick style comment, but perhaps the point of the “nit” prefix is to say, “I know you are a good engineer, and this seems like a silly thing to point out in a code review, but I wouldn’t be doing my job well, or showing respect for the code base, if I overlooked this, so please accept my apology in advance in case you are offended by the following comment.” I guess that is worth a few extra letters, so from now on, I’ll prefix my style comments with “nit.”

  1. Yes, I believe that in a language with a keyword if, there should be a space before the parenthesis that starts its condition. No space after a word indicates a method call, and in Java, if is not a method call. And yes, I know that Checkstyle can check for this. In fact, in the project that Derrick was working in, we have Checkstyle configured to do just that. Consider this an example for the sake of the argument.