in Practices 607 Words

Absolutes

As time goes on, I’m distancing myself more and more from rules that you must always follow or guidelines that make you lean towards absolutes.

  • Commenting every method and variable.
  • Documenting all classes.
  • Coding guidelines that need to be applied everywhere exactly the same way.
  • Over 90% test coverage.

The problem with these rules is that they don’t have any reasoning or intelligence behind them. You must comment everything even if it doesn’t make sense because some tool is checking for it. You must strive for 100% code coverage even if it means writing tests with little business value along the way.

Our strength as developers is our reasoning and our judgement.

I like where these guys are going : Why Inch doesn’t use percentages. They have the right idea. Inch is a documentation coverage tool which gives a you a letter grade rather than a percentage score. Their design takes into account the fact that not everything needs to be documented. Having a grade is less precise that a numerical score but that’s what makes it better. Having a percentage score, particularly with an enforced lower bound will often lead to people gaming the system or fussing too much over the details. Code metrics should be about guiding you to write better code.

Another interesting link on the subject is The code documentation fallacy. The author makes the point that given the choice between 10% or 90% comment coverage, it is better to have 10% because it means the comments that are there have a reason for being there. On the other hand if comments are enforced, most of them will probably be noise.

I can relate to this. I have worked on a large project which required 100% comment coverage of all public classes, methods, method parameters and return values. The team was using a refactoring tool that amongst other things allowed to generate these comments automatically.

I would say about 9 in 10 comments were auto-generated and looked something like this:

/// <summary>
///  The GetName.
///  Returns The GetName.
/// </summary>
public string GetName()

It’s surprising how fast the human brain learns to filter out these useless comments until it doesn’t even notice them. When these comments actually contained useful information they were being gleaned over.

The reverse, absolutely no comments at all, is just as bad. The problem here isn’t the comments or the lack thereof but the inflexible rules.

Google understands this concept as well. If you look at their coding style guidelines documents, (C++, Python, JavaScript) you will see the following:

Use common sense and BE CONSISTENT.

If you are editing code, take a few minutes to look at the code around you and determine its style. If they use spaces around their if clauses, you should, too. If their comments have little boxes of stars around them, make your comments have little boxes of stars around them too.

The point of having style guidelines is to have a common vocabulary of coding so people can concentrate on what you are saying, rather than on how you are saying it. We present global style rules here so people know the vocabulary. But local style is also important.

Notice the mention about local style and the focus on the reasons for having guidelines.

If the person working on the web service layer, knowing the guidelines, truly believes he should use a different naming scheme for his methods I’d be inclined to trust him. He knows his specific context.

Context and judgement trumps blind adherence to rules. Aren’t they called guidelines anyway?

The world isn’t all back and white. We have to trust ourselves.

Leave a comment