|
|
Re: What's the Most Effective Code Style Policy?
|
Posted: Jul 16, 2007 6:56 AM
|
|
This is so much more entertaining than work on a Monday! I've been on a couple of code standard committees and I've found that after you settle on the big things, the rest gets you more trouble than it is worth. Everybody has their own style and to use Bill's variable declaration (columns vs. single space) as a good example, I don't find a big difference in either one. The columns are slightly easier to read, I guess, maybe, but putting all those tabs or spaces in is a complete waste of time. If we had to do that sort of thing I would write some stupid little emacs macro or python script to "fix" my code after I was done with it.
In my practical experience, after you've covered whitespace, brace alignment and variable naming conventions, the rest will cause you endless headaches. Those things can get easily fixed by a good refactoring tool or by firing off a simple script in your favorite text crunching language, which makes me think they are good candidates for code style.
This gets compounded if you are working on products that have pieces implemented in multiple languages. I've worked on projects that have been 3 parts C#, 1 part VB-something and 2 parts C++. Each language has its own standards and issues and differences that make any one set of conventions hard to follow or enforce. Should I bother putting in a preference for if (p != NULL) over if (!p) in the standard since it is C++ specific? What about forcing VB to use Option Base 0? Do I create separate standards for each language? What about the poor schmuck (me...) who actually has to follow the standards for all 3 since he has to work in all 3 languages?
This gets further compounded by trying to add new standards to legacy code bases. Do you reformat and "fix" the entire existing code base before doing any new work? Do you just write the new pieces using the new standards and leave the old code alone from a stylistic point of view? Do you make an effort to update code as you happen to be in it?
And now, since I'm late to the party, to reply to a few points in no particular oder.
> > I've come to believe that having a coding style is
> > important, but enforcement is not:
>
> I have to disagree here. For the java projects I work with
> I have created Unit Tests that execute PMD, Checkstyle and
> FindBugs. If a style checker fails, the build servers
> sends me an email. This way you get used to writing
> quality code, and you get the feedback very soon so fixing
> it is simple. My favorite check is cyclomatic code
> complexity, whenever this check fails I have to rethink
> and refactor the code into something simpler, which can be
> annoying but makes the code much more maintainable.
>
> Also, with annotations you can disable style checks for
> specific code parts if there are good reasons to do so.
As long as you can disable it when the need arises, great. I think you need to be careful about code passing the style checker being quality code, though. After all, would you consider trying to ware a pear of shoes? Did you comb yore hare this mourning? Those pass spell checkers well enough but are, well, silly.
>Things like bracket placement and blank lines should never be an issue because, these days, no one should be writing methods of more than a dozen lines; and in small methods the distractions of style differences are minimised.<
This is in direct contradiction with studies Scott McConnell cites in Code Complete. Personally I think artificially shortening routine length to fit some prescribed notion of the right number of lines will hurt more than help your code. I try to keep functions short but 12 seems to be a very small arbitrary number to use as an upper bound. Pages 173 - 174 of Code Complete, second edition contains a good discussion about routine length. The optimal size, for a variety of reasons, according to Code Complete seems to be about 10 times your desired maximum.
>I wonder if the tab or spaces intent war has over?<
Nope. It still rages on. There is an uneasy truce in python land since whitespace is significant in python, but even there the occasional battle flares up from time to time.
>As for how granular it should be, that's simple: make it as granular as needed, without spending too much time on it. Start with a basic policy everyone agrees on, and as soon as an issue arises, resolve it by adding a new rule.<
Given how personally some people take style, this is anything but simple. I've been on a couple of code standard committees and after you agree on the big things like use of spaces, variable names and brace alignment, it all hits the fan.
I think the most effective coding style policy is short and covers few items. In fact, if it is that important to you, I would talk specifically about your code style policy during interviews. Chances are that the more items the interviewee jives with in your code standards, I think the better they will fit your organization. After all, code is an expression of thought (probably the reason people take coding style so personally) and if their expression fits your predetermined idea of 'good' code, I think you have a pretty good indication that they may be a good fit for your organization, all other things being equal.
|
|
Previous Topic
