About style guides && code conventions

by Sergio Álvarez

Weeks ago, I’ve been moved to a new project at work. My tasks now are focused on maintain an Ariba-based application that is extended by using several Java modules. Speaking out: understanding and bugfixing other’s code.

With this premise, once I came to my new team, I started to investigate if they had some kind of style guide for maintaining such a monstrous project. It was a bit disappointment to see (once again) how this computing world works. No style guide. No code conventions. Because of this, I started to talk with my mates about the benefits of establishing a few guides and conventions for improving the maintenance times. They agree, so I got to work. While I thought this tasks would be easy (or at least, fast),  I was positively surprised to see how complex could be define a good style guide which may help the team to go through clear conventions.

Besides of some obvious points, such as:

  • Lines’ max length
  • Braces position
  • Blank lines
  • White spaces
  • Indentation

I was confused about some other (more philosophical) questions:

Where is the limit?

Should I recommend using one control structure over another?

Should I write about best practices such as: working with many modular and small methods?

Does the style guide have the responsibility of recommend clear names for variables and methods?


What is the real scope for any style guide?

In my opinion, the perfect style guide is one that allows programmers feel comfortable using it (this is not a prison!), but, also by creating some common criteria that reduces the times for understanding the other’s code and optimizing the time for merging conflicts at SVC. There is no reason for developers going crazy. Just make a few guidelines for formatting aspects. Code conventions are not the solution for other background problems…