97 Things Every Programmer Should Know

Chapter 4. Automate Your Coding Standard

Filip van Laenen

YOU’VE PROBABLY BEEN THERE, TOO. At the beginning of a project, everybody has lots of good intentions—call them “new project’s resolutions.” Quite often, many of these resolutions are written down in documents. The ones about code end up in the project’s coding standard. During the kick-off meeting, the lead developer goes through the document and, in the best case, everybody agrees that they will try to follow them. Once the project gets underway, though, these good intentions are abandoned, one at a time. When the project is finally delivered, the code looks like a mess, and nobody seems to know how it came to be that way.

When did things go wrong? Probably already at the kick-off meeting. Some of the project members didn’t pay attention. Others didn’t understand the point. Worse, some disagreed and were already planning their coding standard rebellion. Finally, some got the point and agreed, but when the pressure in the project got too high, they had to let something go. Well-formatted code doesn’t earn you points with a customer that wants more functionality. Furthermore, following a coding standard can be quite a boring task if it isn’t automated. Just try to indent a messy class by hand to find out for yourself.

But if it’s such a problem, why is it that we want a coding standard in the first place? One reason to format the code in a uniform way is so that nobody can “own” a piece of code just by formatting it in his or her private way. We may want to prevent developers from using certain antipatterns in order to avoid some common bugs. In all, a coding standard should make it easier to work in the project, and maintain development speed from the beginning to the end. It follows, then, that everybody should agree on the coding standard, too—it does not help if one developer uses three spaces to indent code, and another uses four.

There exists a wealth of tools that can be used to produce code quality reports and to document and maintain the coding standard, but that isn’t the whole solution. It should be automated and enforced where possible. Here are a few examples:

• Make sure code formatting is part of the build process, so that everybody runs it automatically every time they compile the code.

• Use static code analysis tools to scan the code for unwanted antipatterns. If any are found, break the build.

• Learn to configure those tools so that you can scan for your own, project-specific antipatterns.

• Do not only measure test coverage, but automatically check the results, too. Again, break the build if test coverage is too low.

Try to do this for everything that you consider important. You won’t be able to automate everything you really care about. As for the things that you can’t automatically flag or fix, consider them a set of guidelines supplementary to the coding standard that is automated, but accept that you and your colleagues may not follow them as diligently.

Finally, the coding standard should be dynamic rather than static. As the project evolves, the needs of the project change, and what may have seemed smart in the beginning isn’t necessarily smart a few months later.