Code Conventions

Like revision control, fresh graduates are introduced to the foreign concept of code conventions (or “coding standards”) once they enter professional software teams. As implied by the term, “code conventions” are a set of standards and guidelines that developers have to follow when coding in their software project.

Contrary to what many people think, code conventions are not there simply to make code style consistent throughout large projects with hundreds of thousands of lines of code. Nor is it simply an unnecessary tool used by senior developers to assert their control over the project that only complicates coding.

In fact, properly defined code conventions help manage complexity.

In the book Code Complete, Steve McConnell explains how code conventions do this:

Many of the details of programming are somewhat arbitrary. How many spaces do you indent a loop? How do you format a comment? How should you order class routines? Most of the questions like these have several correct answers. The specific way in which such a question is answered is less important than that it be answered consistently each time. Conventions save programmer the trouble of answering the same questions–making the same arbitrary decisions–again and again. On projects with many programmers, using conventions prevents the confusion that results when different programmers make the arbitrary decisions differently.

McConnell then spends the rest of the section giving the specific merits of code conventions. They’re too many to list down in this simple blog post so I’ll just give a brief overview of a single benefit: consistent practical layout and style.

—

Any fool can write code that a computer can understand.
Good programmers write code that humans can understand.
-Martin Fowler

Properly designed code conventions allow developers to code aesthetically pleasing programs. While it is true that “good looking” programs do not perform better than “ugly” programs and that having to follow guidelines might increase initial coding time, it is also true that a great deal of effort is spent on bug fixing and maintenance and ugly programs take a lot more effort to debug or extend than those with decent layout and style.

Aside from that obvious reason (seriously, what self-respecting software house would allow their developers to write ugly code?), code conventions provide consistency in the appearance of the code throughout the project. It may not be obvious for some who haven’t had the opportunity to wade through hundreds of thousands of lines of code, but seeing different layout styles in different files can be irritating enough to break someone’s concentration.

Imagine seeing half of the code files written this way:

public class StyleNumberOne
{
  private int value;

  public int getValue()
  {
    return value;
  }

}

Then seeing the other half written like this:

public class StyleNumberTwo {

    private int value;

    public int getValue() {
        return value;
    }

}

And have some other code files written by a maverick developer looking like this:

public class StyleNumberThreeIndentedByTabs
{
        private int value;

        public int getValue() {
                return value;
        }
}

Then imagine that you’re the new non-regularized developer (i.e. no vacation leaves yet) tasked to fix their bugs while they all take their Christmas vacation.

Before you suggest running all of their code to an automated code formatter (like in Eclipse) to align the layouts, take note that doing so will mess up the diffs in revision control. That is, it would be very difficult to see what the differences between the code before and after the code format.

With these two simple examples, you should understand by now the significance of something as “trivial” as layout and style conventions.

—

The concerns I mentioned before (unnecessary complexity, angry monkeys), however, also have merit and the book acknowledges this. McConnell also warns against the opposite in the same paragraph:

Programmers on large projects sometimes go overboard with conventions. They establish so many standards and guidelines that remembering them becomes a full-time job. But programmers on small projects tend to go “underboard,” not realizing the full benefits of intelligently conceived conventions. You should understand their real value and take advantage of them; you should use them to provide structure in areas in which structure is needed.

Fortunately, most programming languages today provide official code conventions to reduce the drafting effort. For example, Sun has a page devoted to Java Code Conventions. Take note that software teams still have the final say in their standards, as some standards may not be applicable depending on the overriding culture of the team (e.g. may cause pointless debates or whatever).