Standards Document

Question

I am with writing a coding standards document for a team of about 15 with a load of between 10 and 15 projects a year. Amongst other sections (which I may post here as I get to them) I am writing a section on code formatting. So to start with, I think it wise that, for whatever reason, we establish some basic, consistent code formatting/naming standards.

I've looked at roughly 10 projects written over the last 3 years from this team and I'm obviously finding a pretty wide range of styles. Contractors come in and out and at times, double the team size.

I am looking for a few suggestions for code formatting and naming standards that have really paid off ... but that can also really be justified. I think consistency and shared-patterns go a long way to making the code more maintainable ... but are there other things I ought to consider when defining said standards?

• How do you lineup parens? Do you follow the same paren guidelines when dealing with classes, methods, try catch blocks, switch statements, if else blocks etc.

• Do you line up fields on a column? Do you notate private variables with an underscore? Do you follow any naming conventions to make it easier to find particulars in a file? How do you order the members of your class?

What about suggestions for namespace, packaging or source code folder/organization standards? I tend to start with something like

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName

and I'm curious to see if there are other more accepted practices that what I am accustomed to before I venture off dictating these standards. Links to standards published online would be great too - although I've done a bit of that already.

Answer 1

It obviously varies depending on languages and technologies. By the look of your example name space I am going to guess java, in which case http://java.sun.com/docs/codeconv/ is a really good place to start. You might also want to look at something like maven's standard directory structure which will make all your projects look similar.

Answer 2

First find a automated code-formatter that works with your language. Reason: Whatever the document says, people will inevitably break the rules. It's much easier to run code through a formatter than to nit-pick in a code review.

If you're using a language with an existing standard (e.g. Java, C#), it's easiest to use it, or at least start with it as a first draft. Sun put a lot of thought into their formatting rules; you might as well take advantage of it.

In any case, remember that much research has shown that varying things like brace position and whitespace use has no measurable effect on productivity or understandability or prevalence of bugs. Just having any standard is the key.

Answer 3

I'm going to second Jason's suggestion.

I just completed a standards document for a team of 10-12 that work mostly in perl. The document says to use "perltidy-like indentation for complex data structures." We also provided everyone with example perltidy settings that would clean up their code to meet this standard. It was very clear and very much industry-standard for the language so we had great buyoff on it by the team.

When setting out to write this document, I asked around for some examples of great code in our repository and googled a bit to find other standards documents that smarter architects than I to construct a template. It was tough being concise and pragmatic without crossing into micro-manager territory but very much worth it; having any standard is indeed key.

Hope it works out!

Answer 4

Coming from the automotive industry, here's a few style standards used for concrete reasons:

Always used braces in control structures, and place them on separate lines. This eliminates problems with people adding code and including it or not including it mistakenly inside a control structure.

if(...)
{

}

All switches/selects have a default case. The default case logs an error if it's not a valid path.

For the same reason as above, any if...elseif... control structures MUST end with a default else that also logs an error if it's not a valid path. A single if statement does not require this.

In the occasional case where a loop or control structure is intentionally empty, a semicolon is always placed within to indicate that this is intentional.

while(stillwaiting())
{
   ;
}

Naming standards have very different styles for typedefs, defined constants, module global variables, etc. Variable names include type. You can look at the name and have a good idea of what module it pertains to, its scope, and type. This makes it easy to detect errors related to types, etc.

There are others, but these are the top off my head.