Re: Why Create Coding Standards and Perform Code Reviews? (how not to)by tye (Sage)
|on Jul 03, 2009 at 04:29 UTC||Need Help??|
Coding standards will also inevitably be sources of contention and frustration. I've found that much of this is avoided by being careful to set the right tone. This has to be done officially, as part of the coding standard.
Clearly state that the "rules" in the coding standard are suggestions. There can be situations where it is appropriate to "violate" a standard, but such cases should be exceptions, usually pretty rare exceptions (varies from "rule" to "rule"). If you can't explain and justify why you violated a rule, expect to be told to fix your violation.
A coding standard can't get better if you don't allow your programmers to discover and explore better ways of doing things. So an unchangeable coding standard leaves your code base locked in a increasingly out-dated box.
Of course, this flexibility completely blows away your "enforce rules with a tool", which I think is a horrid idea. Running code through a "tidy" step is only going to be close to reasonable for extremely simple rules (and reasonably simple languages -- ie, not Perl). Some of the stupidest coding conventions I've run into were things done as to not break some tool like a tidy step or a popular syntax highlighter or vi's % key. The results were almost as bad as the stupidest things perltidy did by itself (when people used it on their own, not because we mandated that it be used).
If the tool is good enough, the language regular enough, the rule simple enough, and the consequences of violating dire enough, then it can make sense to run the tool as part of the check-in process (note that perltidy fails all of these tests). The risk of a false-positive needs to be extremely high to burden your programmers with it constantly being run. Having the tool adjust the code being checked-in is always a bad idea, in my experience.
Enforcement tools like Perl::Critic, in order to appear extra useful, tend to come configured with a large array of tests (either from the tool distributor or the people who "adopt" it in your organization). This is the wrong way to go. Most of those rules won't pass the above tests. Even an excellent rule can become a hardship if it gets enforced by a mindless automaton (producing code splattered with comments to tell your 'linter' to "shut up!" isn't a "win" in my book).
I've implemented during-check-in enforcement rules in order to detect (accidental) violations of very simple rules with serious consequences (inclusion of "\r" in source code, which was causing horrible problems with merging in our version control system -- to the point of introducing post-merge bugs). I've implemented automated detection of more complex rules that had more severe consequences but these were run much less often (the ones that come to mind are too complex to explain here).
Even slightly complex rules are better enforced by people capable of exercising judgement (which might exclude some of your co-workers), even if those people use tools to help them.
With each "rule", include justification. Over time, your coding standard needs to be able to adapt. A great way to cause aggrevation is to answer "Why can't we do X?" (by which your programmer means, "why does our coding standard say not to do X?") with "That is the style we standardized on 10 years ago. I don't remember why."
If you justify each "rule", then each programmer is more likely to understand the benefit of the rule and thus to accept it (I've balked at many coding standard rules and then later had the benefit explained and stopped balking). If the justification given is weak, then that is great, because it means it is easy to get rid of or replace that rule with one that somebody has a much better justification for.
If the justification is excellent, then it guides how the rule can be adapted (including being replaced by a better rule). Often you'll also adjust the justifications.
Taking this tone means that more of your coding standard is likely to be seen as something that your programmers can learn from and can contribute to. This is why I prefer "best practices" (though that term has also become popular among people who implement dogmatic regimens so some find that term has a negative connotation).