What should coding guidelines do, and are there any good examples of guidelines? [closed]

Question

What are some good examples of coding guidelines. I'm not really looking for anything specific to a single language.

But what should I be doing/evaluating as I write coding guidelines? Such as how flexible should the guidelines and how much should decisions be left to the programmer or to someone else or even pre-decided by the guidelines.

This set of guidelines that I am working on is supposed to cover a wide range of topics: comments, database design, and even some user interface guidelines.

Answer 1

There are generally three purposes for coding standards:

• Reduce the likelihood of bugs
• Reduce the time required to analyze code written by someone else
• Give someone a power trip

Obviously, the third is a waste of everyone else's time, but you do need to consider it, specifically so you don't go down that road.

Having said that, there are some definite do's and dont's that I've noticed:

• Enforce consistent whitespace usage. Tabs, 2-spaces, 4-spaces, doesn't matter. Keep it consistent, so indent levels aren't screwed up by people using different editors. I've seen mistakes made because maintenance programmers misinterpreted the nesting level of a block of code.
• Enforce consistent logging methodology. It's a huge drain on support staff's time if they aren't able to skim over logs, because everyone's module logs for different reasons, and everyone has a different definition of Info vs. Warning vs. Error.
• Enforce consistent error handling. If module A throws exceptions, module B returns error codes, and module C simply logs and moves on, it'll be a pain to integrate them without letting an error slip through the cracks.
• Try to avoid petty things like placement of curly-braces. That's going to get a lot of people arguing over their pet style, and in the end, it really doesn't have a huge impact on the readability of code. On the other hand, enforcing the presence of brackets can make a difference.
• When integrating disparate code bases, don't be tempted to change everyone's variable naming conventions to match the golden standard. You may have a standard for moving forward, but what's most important is that any localized standards that already exist are preserved consistently. If one module uses m_member, a maintenance programmer should be using m_member2 rather than applying any other standard (such as member2_ or m_lpcstrMember2 or whatever). Local consistency is king.
• Filesystem layout is important. Keep it consistent. Make it easy for someone to jump into a library sourcebase and instantly know where are the headers, the Makefile, the sources, etc. If you're working with Java or Python, this is a no-brainer because the package system enforces it. If you're working with C, C++, or any other myriad of scripting languages, you'll need to devise a standard layout yourself and stick with it.
• Don't sweat the little stuff. Variable naming conventions, spaces between parentheses or keywords or function names... most of that doesn't matter, because it doesn't reduce the likelihood of a mistake. Every rule you set should have a concrete rationale, and you shouldn't be afraid to change or remove it if you discover it's causing more grief than it's worth.
• Don't enforce gratuitous comment blocks everywhere. They'll end up as a waste, and most comments are better off being expressed in the code itself (as variable or function names, for example).

Finally, the most important thing is to have regular code reviews between peers. Encourage people to speak up when they see a "code smell." Also be sure people realize that constructive code criticism is not meant to be personal - the source is shared by everone on the team, it doesn't just belong to the original author. In my experience, the most heinous problems have been design problems that wouldn't have been solved by any amount of coding guidelines. Software design is still something of an art form (for better or for worse), and a pool of brains is much better than a single one.