Tuesday, September 30, 2008


I wrote yesterday about evaluating test code, and wanted to follow up about the use of style. Much of what I discussed was a case of right or wrong, will or won't scale, can or can't be maintained; it's fairly black or white. Things get grey very quickly, however, when we start talking about style guides. After all, who cares if you put a space between your arguments or not?

The short answer is that I care, and you should, too. After all, consistency matters.

Why do we care about consistency and style?
There are a number of reasons to care about consistency.
  • Consistent code is easier to read. Your eye starts to look for standard clues in formatting (quote blocks, loop layout, etc.), and when it's there you comprehend more quickly.
  • Crossing editors is easier. Not everyone is going to use the same tools, or even the same OS. Having style guidelines helps things work on everyone's environment, not just yours.
  • Bugs are in the inconsistencies. So you didn't lay your loop out with the braces in the normal location, so what? But then when someone changes your loop, they'll make the code consistent - and now you've got an extra brace and a bug. Sure, it's an easy bug to catch (thanks, compiler!), but it didn't have to be a bug in the first place. The same thing is true on more subtle levels (think array indices, for example).
What are the elements of a style guide?
The specific elements of your style guide will vary based on language, environment, age of code base and the personal preferences of the person creating/enforcing the code style. However, areas that are covered usually include:
  • Comment formatting. This applies to both contents and layout of comments. It is particularly important when you're using a doc generator.
  • Whitespace, indentation, and braces. These help in particular in mixed environments, where "tab" may not mean the same number of spaces everywhere, for example. Brace usage can, depending on language, allow for increased maintainability when moving from one-line clauses to multi-line clauses. Most of this formatting is about making code really fast to read, so you can simply assume the formatting and really see the code flow easily.
  • Naming. Method names, variable names, class names, constant names will all have a style so that it's easier to distinguish them.
  • Scoping. Making scope as narrow as possible is generally the guideline here.
  • Exception throwing and handling. How many exception types are there? Should you swallow the exception, throw it higher, leave it?
  • Overloading. When overloading is good versus when it's discouraged varies greatly.
  • File and method ordering within classes. Make things easier to find without using your IDE's "open declaration" feature (if your IDE has that).
Sometimes, even with a style guide, you'll find yourself violating the style. You may change styles and not immediately refactor all your code. That's okay - total consistency is not the goal. The goal of coding styles and style guides is to help you better read/write/maintain code as a whole team - current and future. Don't let your style run away with delivering value, but don't let delivering value today be so poorly styled that you can't keep and increase that value tomorrow.

And remember, your test code is code, too. Make it stylish!

No comments:

Post a Comment