Ensuring Code Consistency

From AndrewMoore

Each time I go to YAPC, I come back highly motivated. While I am usually quite motivated to add features to whatever project I'm working on, I'm always heavily motivated to improve the consistency of my current project's codebase. This may be because I see all of the tools available to the perl community that attempt to encourage and enforce code consistency. It may be because I listen to people like chromatic talk about the benefits of having a consistent code base. They often don't call it this, but it's one aspect of what is often preached. When I get back to work, I usually devote a bit of time improving the consistency of the code base and I see some benefits of that work. Read on to see what benefits I'm talking about and how you can make some simple changes to improve the usability of your code base.

What do I mean by code consistency?

Code, like spoken language, can develop a dialact. When you're first starting out with a particular language or in programming in general, you're likely to write in simple dialect, analogous to Pidgin English. Software projects can develop their own dialects, too. Going beyond code layout which includes such practices as indentation and use of vertical and horizontal whitespace, there are decisions such as which idioms to use in particular situations. For example, in perl there are usages like postfix control statements that can be used to make code much more or less readable. Using these in a consistent manner through an application defines the dialect for that code. Variations lead to surprises for programmers and distract them from the real objective of using code to solve problems.

Concentrate on what the code does, not how it does it

Having a consistent code base can help programmers focus on the more important topic of solving problems, not the trivial topic of how to lay out the code. Here's how:

It encourages group code ownership and discourages dialacts in your code. Often if you have a handful of contributors, some parts of your application are written a bit differently than others. This can result in programmers not wanting to edit certain parts of the code because they're "old" or "crufty". In other words, they're written differently than the more comfortable parts of the code. Or, even worse, some parts of the code become the "turf" of a particular programmer. Having to depend on a particular member of a team to edit one particular part of the code is a risk and a cost to not having a consistent code base with group ownership.

Your editor can make small decisions for you. Modern editors can fill in in templates for common chunks of code. They can tell when you start a for loop or a new method and will fill in the surrounding structure of braces and keywords. Or, they can automatically indent regions of text for you. relying on this automation removes the small decisions on how to indent from your contributors so they can focus on the larger, more important tasks like making sure the code works. If they have to remember that in one region of the code, indentation is done differently or lines are broken up differently, they can't rely on their editors and are instead reduced to making these small decisions themselves.

You can spend less time picking a good way to do something. If you know that you always use a particular idiom to solve problems of a particular type, you don't have to spend time deciding between a handful of equally good ways to solve a particular problem. You can spend that time thinking about more important things.

It improves the morale of contributors by not letting them spend time lamenting other contributors' styles. Team members sometimes become aggravated by the different ways that other contributors solve problems or format their code. Going deeper than just the argument between indenting with tabs or spaces, the different ways to say the same thing in code can distract programmers from the more important job of solving problems in code.

It can automate a part of your code review by removing the discussion about how to write a particular piece of code. If you have a tool which can make the decisions about code layout and commonly accepted coding practices, then you can remove that part of your discussion from the code review. Make the code review shorter, more efficient, and more productive by letting the programmers talk about things that can't be solved by a static analysis tool.

Tools to help you ensure consistency

These tools are pretty perl specific, but your language surely has similar tricks and tools to help you ensure your code looks the same throughout.

perltidy can be used to help ensure a consistent layout of code. For the most part, this tool only deals with whitespace changes, both vertical and horizontal. Agreeing on a common perltidy configuration and usage can help reduce the arguments over minor differences in code. While the arguments over how perltidy should be configured may indeed be heated, at least you can have them once and be done with it. After that, you depend on the tool to determine which layout is the correct one.

Perl::Critic also helps enforce code consistency. It is designed to make your code comply with a set of "best" practices for perl development, so while you develop consistency, you also will produce code that is supposed to be more usable and readable. it's worth investigating.

Documentation coverage and correctness tests can be run to ensure that all methods are documented and that there are no syntax errors in your inline documentation. A set of documentation templates can go a long way to make sure that each of your modules are documented in a consistent way.

Module templates are another great way to ensure that your modules or classes all look the same. Module::Starter can also help to ensure a consistent set of modules.

Your turn

I've shown you some easy ways you can strive to make your code a little more consistent throughout and the benefits to doing it. Now, it's your turn. What can you add to your procedures or to your test suite to make sure that your code is more consistent?