Coding Standards Revisited: Tips For More Readable Code

In my previous post, Coding Standards Revisited: My Language Agnostic Coding Standards, I talked about some non-traditional language agnostic coding standards that I believe apply to all code on all (modern) frameworks, languages, and platforms. In today's post I want to talk specifically about some standards that can increase (or decrease if ignored) the readability of your code. As I've argued before maintainability is crucial in the craft of software development.

So let's talk about a few readability coding standards that I like to use. When adhered to they greatly increase the readability, and therefore maintainability, of your code.

Meaningful Variable Names

Use meaningful names. x is not meaningful. client is not meaningful. provider is not meaningful. Chose names that are specific to the domain you are in. Chose names that clearly define the value of the variable. For example rowIndex is more meaningful than x.

Shorthand Variable Names

DO NOT use shorthand for variable names. Shorthand assumes that you have a shared context from which the shorthand was generated. It becomes difficult for members of other teams or new team members to read your code if you use shorthand.

Private Variables

DO NOT use _ to denote private variables. The English language doesn't use _'s to start words. So starting variable names with _ causes the brain to do more work in recognizing the pattern. I would strongly suggest casing your private variables the same as function variables and differentiating them using keywords like this or self if your language supports them.

Constants

If there is one place I am willing to break from the language standard for my own standard it's with constants. I usually use all caps for constants whether they're private or public. I've found that even developers that haven't been traditionally exposed to this style can figure it out intuitively pretty quickly.

With that said, if your language does provide a standard for how Constants are defined you should try to first adhere to that already defined standard.

Variable Scope

I make all member variables private. Even variables that may be subject to change from outside influence. Exposing private variables as public or even protected means that the state of your class can change without the class having an opportunity to respond to the state change.  This is often the cause of bugs in the system (hard to find bugs at that).

Define get or set methods for your class if your really have to expose the value of a member variable. Having a set method allows the class to control the change and therefore giving it an opportunity to keep it's internal state consistent.

Some languages provide syntactic sugar for the get/set methods and should be preferred to more explicit get/set methods.

Curly Braces

Use curly braces according to the standards of the language you're writing in. Don't just arbitraily put curly braces on their own line or on the line of the block their defining. Different languages have different standards for curly brace style. In fact, some languages support curly braces but use the convention of not including them except in specific scenarios.

It's better to deal with uncomfortably in looking at curly braces than it is for you to be non-standard. In my experience I've found that it really only takes a week or two to get used to the curly brace style of the language you're using.

Whitespace

There's nothing more annoying then checking in code for a one line change only to notice that the diff shows 500 lines changed. What happened? You, or the person who last touched this file, is using a different standard for whitespace. Nowadays, most IDE's auto-format the code for you. So even if you don't change a line of code the whitespace may change to bring the file into conformance with whatever your IDE preferences have been set at.

Define your use of whitespace such that a standard developer for that language would expect them. If there is no guidance for your language on whitespace choose the use the default for the most common editor or IDE for that language.