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.

The Intelligent Code Completion Nightmare

The other day I wrote a blog post on why I don't use a traditional IDE. If you haven't read you go check it out. I got an interesting email response (a comment would have been better) from a friend of mine about a particular part of that post; Intelligent Code Completion. Here's what my friend had to say about ICC.

I am arguing against the idea that it either discourages or encourages the learning of a new system - instead, it can assist with either!"

my argument is basically that one's desire to grok a particular system is a personal one, driven by various motivations ("to each his own"?), and that although ICC makes it easier to avoid diving into the nuts and bolts, it greatly helps those that do want to learn

After reading this I can see that my argument against ICC is one sided. It only focuses on the negative side of ICC. That's mostly due to the fact that, in my experience, I've seen it have a negative impact on more people than it's had a positive impact on. But my friend is correct that it can be used as a tool to help those who truly want to learn.

I think I understand why I've seen it have more of a negative impact than a positive one. I think that people tend to fall into 4 general categories when it comes to learning.

• Want to learn and are disciplined
• Want to learn but are not disciplined
• Don't want to learn and are disciplined
• Don't want to learn and are not disciplined 

People in the first category are the folks that you interact with that "just get it." They're the ones that tend to grok things quickly because they've learned discipline around learning and have become efficient at it and have learned how to learn things that are difficult for them. These people are VERY successful in their jobs. I think this group makes up like 5% - 10% of the average software development shop. These people benefit from ICC.

People in the second category are people who "are hard workers". They tend to understand systems but it takes a lot of work. Usually a lot of trial and error. These people tend to gravitate towards particular types of learning (learn by example, classes, learn by reading, etc...). These people are successful in their jobs. Some of them are really successful and some are just mildly successful. I think this group makes up anywhere between 50% - 70% of the average software development shop. These people are, in general, hindered by ICC but believe that it helps them. They are not typically aware that it takes them more effort to learn because of their lack of discipline.

People in the third category are the people that "just get by". They don't tend to make it very long in any particular organization. They stay for a year or so before they get fired or they get frustrated and leave. They tend to be satisfied finding solutions to their work on Google or Stack Overflow and leave it at that. They don't typically dive in to find out why the Google or Stack Overflow answer works. They're pretty efficient at finding the answer though because their discipline helps them out. These people are hindered in the long run (i.e. growing in their career) by ICC but are helped in the short term. I think this group makes up anywhere between 20% - 30% of the average software development shop.

People in the last group are just there to collect a paycheck. They don't really care about technology, they only care that technology jobs pay well. ICC actually helps these people stay in their jobs because it removes some of the tediousness of learning. ICC hinders their employers in rooting them out and moving them on sooner because they can do just enough to get by. I think this group makes up like 5% - 10% of the average software development shop.

Because the second and third category of people make up the vast majority of people in the office, and are in general hindered by ICC, I tend to see ICC as a negative.

What are your thoughts?