I can’t claim to be an expert writer—not in English, and not even in my native languages—but I do put a lot of attention to whatever I write: emails, presentations, letters and, of course, code. As it turns out, code has prose in it most of the time in the form of comments and documentation.
So, when you write any text in your code, engrave this in mind: any obvious typos and/or any grammar mistake very quickly denote sloppiness in what you wrote. If that is the impression the reader gets from your comments… why would he trust that you have been less sloppy when writing the code itself? Let me tell you that they won’t, with good reason.
Some details to pay attention to that I keep encountering over and over again while reviewing code:
- Write full sentences, always. That means using capitalization where due and sentence-ending periods.
- Pay attention to proper names and capitalize them accordingly.
- Commas are not sentence terminators. Use a semicolon or a period to connect full, standalone sentences.
- Enable the spellchecker in your code editor, if available. This will catch an awful lot of typos.
But the most useful thing you can train yourself to do is: read whatever you have written twice at the very minimum. Most obvious errors will show up on those subsequent reads and you will have a chance to fix them. And yes, this applies to emails as well.
That’s it for today on readability. Yes, this post is shorter than usual but a) it had to be said and b) there is not much more to add!
