Coding Standards
Posted by Uncle Bob on 04/18/2007
Coding Standards are a good idea. Every team should adopt a coding style and standard, and stick to it. The code produced by that team should have a consistent look and feel that is devoid of individual preferences and fetishes.
Of course this means that the members of the team will have to be mature enough to realize that it doesn’t really matter where they put their braces, or how they adorn their member variables. What matters is that they all use the same conventions.
Consistency
My goal for a good coding standard is to eliminate individual styles in favor of a team style. The code produced by a team should look like the team produced it. I don’t want any code recognizable as Bob’s or Bill’s.
This is not some egalitarian fantasy to hide individuality for the sake of the collective. Rather, it is a raw necessity. We’ve all seen products that look like they were designed by a committee. We’ve all used software products where the look and feel changed depending on which part of the application you were using. The result feels messy, clumsy, inefficient.
Individuals, used to their own particular style, will reformat other people’s code when forced to work on it, further shuffling the patchwork of styles. Over time, as each team member touches different parts of the code, and team members come and go from the team, the code begins to look like a jumbled Rubick’s cube of different styles.
Code is a product, in and of itself. The team producing it needs to take pride in the elegance of it’s structure, and the expressiveness of it’s presentation. This kind of pride is infeasible when the code is crisscrossed with a patchwork of individual styles. Without this pride, there is no drive to keep the overall product clean. Without that cleanliness, messes build up at the boundaries. And, as we all know, messes slow us down, and they spread.
Style not Substance
A good coding standard should be about style and form, not about substance. It should not attempt to legislate good design. It should not, for example, proscribe goto or public variables. Those rules are part of the body of knowledge that all software developers should have, and are not a matter of style.
Coding standards should be about the things that don’t matter. They should be about brace placement, naming conventions, the use of blank lines, indentation levels, etc. A coding standard should describe the way code looks, not the substance the code is made from.
It is important to keep style and substance separate because they matter for different reasons. Issues of style matter only for consistency. It does not matter whether your indent depth is 2 or 4, so long as everyone uses the same depth. It does matter if you use public variables inappropriately.
Oral/Code Tradition
Documents that describe coding standards tend to be useless. They often become a bloated battleground for many different competing ideas. My advice is to avoid writing them.
The real document that describes your coding standard is your code. If you want to know how to name a variable, look at how they are named in the code. If you want to know what the standard indent depth is, look in the code. The code is the living document that describes the coding standard.
Oral tradition plays a role as well; especially when communicating issues of substance vs. style. Teams should make use of code reviews and pair programming to communicate with each other about issues of style and substance. New members of the team should have frequent exposure to the more seasoned members, so that the issues of style and substance are inculcated with moral authority. Nothing is quite as persuasive to a young programmer than pairing with the lead programmer and hearing him say: “We don’t do things that way; we do things this way.”
The Tyranny of Tools
I have seen teams attempt to enforce a style through the use of tools. Some tools are benign and helpful. Many IDEs, for example, allow you to specify things like indent level, brace placement, etc. With a single keystroke you can ensure that a batch of code conforms to the team style. I use tools like this, an depend upon them. I make sure that all the team members set their IDEs to use the conventions.
Other tools can be more intrusive. Some tools can act like compilers, generating errors if the style is not adhered to. Such tools might be useful for an occasional scan of the code; but I think you have to be very careful if you put them into the normal build cycle.
Automatic enforcement is power; and power corrupts. We do not want a well-meaning bureaucrat deciding, one day, to enforce the style that every function argument must have a javadoc comment. This leads to comments of the form: //required comment.
This is not to say that tools like findbugs and checkstyle should be avoided. Indeed, I find them very useful. However, I think they should be run occasionally and manually, not as part of every build. The issues that these tools discover should be dealt with on a case-by-case basis.
Many tools like this allow you to insert special meta-comments that override the warnings. If these tools are placed in the build process; then the code will become cluttered with these meta-comments.
I have a pathological distaste for meta-comments.
Conclusion
Coding style is a matter of team pride and team identity. Teams should be free to adopt their own styles, and to change those styles as the spirit moves them. Each member of the team should follow the team style, and work to ensure that the body of code is a consistent statement of that style. If this sounds too artsy-fartsy, keep in mind that pride of workmanship is a powerful motivator. We want teams to be proud of their creations.
Comments
Tim about 8 hours later:
I think that incorporating lint in builds has been helpful for C++ and C in the past. There is always some effort to set up the warning levels, and I hate to see code littered with lint-disabling comments (though they are an indicator of where the problems are ).
I agree that a coding style is an important part of the team experience, and it really doesn’t matter which style is chosen. As an opinionated jerk once wrote,teamwork is submission.
Brian Slesinsky about 14 hours later:
Right on! I just want to emphasize this point:
“Teams should be free to adopt their own styles, and to change those styles as the spirit moves them. Each member of the team should follow the team style, and work to ensure that the body of code is a consistent statement of that style.”
(Tired of the company style.)
Robert Jason 1 day later:
This is a fantasy, usually implemented by someone wanting to force their style on others. As an experienced developer, I know style doesn’t matter that much. If I am thrown off by brace placement or the fact that another developer used 2 more spaces for indention or left a couple of blank lines in the code, then I probably shouldn’t be coding to begin with.
Jeremy King 14 days later:
^ “As an experienced developer, I know style doesn’t matter that much”
Obviously, you aren’t THAT experienced or you don’t work in a large team environment.
I think you missed the spirit of the article – fugly code eventually slows us down. Take some pride and ownership in your work as a TEAM.
“The team producing it needs to take pride in the elegance of it’s structure, and the expressiveness of it’s presentation. This kind of pride is infeasible when the code is crisscrossed with a patchwork of individual styles. Without this pride, there is no drive to keep the overall product clean. Without that cleanliness, messes build up at the boundaries. And, as we all know, messes slow us down, and they spread.”
Paul Peaslee 16 days later:
“Documents that describe coding standards tend to be useless”
On the contrary, style documents help new team members become acclimated quickly.
The standard style should be explained in the team’s style document and be mandated by the development environment used by the team. The style document should also explain how to setup the style standards in the development environment used.
I’d never rely on oral tradition. I don’t believe that you could get any two team members to define the standard style in the same manner. Perhaps after reading the style document, a new member might ask an older member why he doesn’t always follow the standard.
As a sometime team leader, I really hate having to excuse someone for not following the rules because something wasn’t written down.
A tip: Paul Haeberli’s “The SGI C Source Compliance Requirements” (http://www.graficaobscura.com/ccode/index.html) chart is a great example of the beginnings of a style document.
bd
Matthew J. Lesko 16 days later:
“A foolish consistency is the hobgoblin of little minds.” - “Self-Reliance†by Ralph Waldo Emerson
“The Fundamental Theorem of Programming is that good visual layout shows the logical structure of a program.” - “Code Complete” by Steve McConnell
Read McConnell’s chapters on Layout and Style and Self-Documenting Code in “Code Complete” and Part I of Brian Evan’s “Domain Driven Design” for insight from practitioners about what really works.
George S. Cowan about 1 month later:
Uncle Bob, you said, “Coding standards should be about the things that don’t matter”. But there are real issues that are addressed by style; for instance, allowing programs to be shorter and more readable by using horizontal and vertical real estate effectively, and allowing insertion of code at the beginning and end of alligned sequences without worrying about punctuation problems. (Some issues that used to be important have gone away, such as requiring that commas only be used in COBOL where they are required, in order to avoid confusing them with periods in poorly inked program printouts.) And there is a large grey area as we move from punctuation to the commonly agreed body of knowledge. So issues of common style are worth some effort.
George S. Cowan about 1 month later:
I’m trying to invent some reasons to have a style document. Here’s all I’ve come up with so far.
One day the team will be gone and a programmer will be maintaining programs from many teams. This programmer will be helped by a consistency in style across teams.
Also, in open source projects we might want to encourage newbies to contribute with as little hand-holding as possible. This could even be a reason to include some issues of substance in the style document and automating the checking with every build.
Of course, once we introduce a style document we introduce the need for the style police, court system, and legislature. So it’s not to be done lightly.
Monis Iqbal 7 months later:
I have heard that Microsoft followed writing opposite condition statements so as to avoid the ”= instead of " mistake. e.g. instead of: if (i 5) they wrote: if (5 == i).
If this is true, then it is a kind of coding convention practiced to avoid symantec errors.
Tim 7 months later:
@Monis:
That was a common practice in C shops and C++ shops for a long time. I don’t think it originated at MS. Yes, it is a standard for avoiding a certain class of error, and it did help even though readability suffers a bit