On Code Style Guides

A short post about why code style guides matter, and an easy way to create one.

Why Code Style Guides?

A coherent code style makes code easier to read because it reduces visual noise and cognitive load. For example, take these two ways to present the same math question:

        |\                      |\               a = 5
        |  \                    |  \             b = 3
    5   |    \   ?          a   |    \   ?
        |      \                |      \
        |________\              |________\
            3                       b

Although, whether you can solve the question doesn't depend on the way it's presented, the first way 'feels' easier.
There's less cognitive strain.

Extrinsic vs Intrinsic Complexity

The question above has intrinsic complexity, that is complexity that's inherent to the problem. You have to know Pythagoras' theorem (a^2 + b^2 = c^2) to solve it.

But, the second way of presenting the problem adds extrinsic complexity to the problem. That is complexity that is not inherent to the problem and is as such unnecessary.

Similarly, badly formatted code adds unnecessary complexity for the reader. Since we are pattern matching machines, even tiny irregularities can lead to short distractions. E.g. a brace in the wrong place, a comma attached to the wrong token, ...

Let's compare two examples. We start with a very messy "code style":

public  class Foo extends  Bar {
  private String _someMember;
    private int SomeOtherMember;

  public Foo(String someParam)
  {
         _someMember = someParam;
  }

  public void do() {
   if (_someMember != null && _someMember.equals(SomeOtherMember.toString())
   {
     if (_someMember.length() > 10) {
       // do something
   }
   }
   else
   {
      // do something else
   }
    }

    public void DoSomethingElse() { _someMember = "foo"; SomeOtherMember = "bar"; }
}

There is no consistent naming, e.g. methods use Pascal (DoSomeThingElse()) or camel case (do()). Indentation is messy, it's hard to see to which if the else belongs, ...

Let's try to get this piece of code more consistent, more readable:

public class Foo extends Bar {
  private String _someMember;
  private int _someOtherMember;

  public Foo(String someParam) {
    _someMember = someParam;
  }

  public void do() {
    if (_someMember != null && _someMember.equals(someOtherMember.toString()) {
      if (_someMember.length() > 10) {
        // do something
      }
    } else {
      // do something else
    }
  }

  public void DoSomethingElse() {
    _someMember = "foo";
    _someOtherMember = "bar";
  }
}

Whether you agree with the specific code style or not, I think we can all agree, that the second version is easier to
read than the first one.

How to Create a Style Guide?

I like to start easy. For example for Java I just use
the Google Java Style Guide with some minor modifications.

If you use an IDE with extensive options to configure a code style, like Android Studio does for example. I like to make it easy on my fellow developers and me. The code style gets configured in the IDE and I only describe the things that cannot be automated/enforced by the IDE. These are guidelines on comments, naming where to best line wrap, ... . An example for a minimal code style guide could look like follows (start small).

%Your Company Name% Java Style Guide

This style guide is based on the Google Java Style Guide.

All formatting is configured in the project's code style settings file, so you don't have to worry about where the braces go, how many whitespaces to use when indenting, ... - this is all being taken care of by the IDE.

There are however a number of things that the IDE can't or shouldn't do for you. These things are addressed in the rest of this style guide.

Ordering of class contents

...

Line-wrapping

...

Comments

...
Use comments mainly to explain why you do something the way you do it. What you're doing should be clear from the code. Use descriptive names for methods and variables.

Every time you write a comment, you should grimace and feel the failure of your ability of expression.

Robert C. Martin

In the end it doesn't matter which style you choose, the only thing that matters is that you do use one.