What are generally accepted code formatting guidelines?

Question

According to McCall's Quality Model, Product Revision is one of the three main perspectives for describing the quality attributes of a software product. Under the Product Revision perspective, maintainability, the ability to find and fix a defect, is identified as a key quality factor that impacts the ability to revise the software.

Clearly, at some point in the revision process, there is a need for human involvement, specifically programmer involvement. The formatting of the code has an impact on the programmer's ability to revise the software effectively and efficiently.

What generally accepted, language agnostic code formatting guidelines have you worked with that maximize programmer efficiency and effectiveness in the code revision process?

Answer 1

The best guidelines I've ever worked with is consistency. Over the years I've used a lot of different styles with different teams ... the best results I've seen is when the whole team is forced to use the same style, regardless of what style it is :-)

Answer 2

I agree with Joel. There are many examples of style out there; most are good. Some are not as useful as others (hungarian notation?) anymore. The whole point is consistency, though. As long as a new developer can come in and understand the code right away instead of having to get used to each individual developer's personal style, it works.

Switching standards every year or so is probably a bad idea.

Answer 3

Consistency is the key. Write down the guidelines somewhere, and require conformance.

Code formatting is not worth worrying about, nor arguing over. Just make some rules, and stick to them.

Answer 4

I agree with Joel, maintainability goes up considerably when you have consistency within your organization. If I join another team the ramp-up time is much less if everything has a similar look and feel to my current because I can read code much quicker w/out all the "inner context switching" to get my head around "so they use mVar instead of _var" / etc

Answer 5

I have a few thoughts about some language agnostic concepts:

1.) Remove dead code. Unless something is absolutely essential, commented-out, dead code should be removed. It clutters up a routine, you'll often get false positives when you search for some string and it shows a general sloppiness that's not good for a professional developer

2.) For maintenance fixes, reference a defect tracking number in a comment--assuming you have some sort of defect tracking system. This makes it easier for anyone maintaining your work to figure out why the code was changed between one revision and another.

3.) For languages that support it, declare variables as close as possible to their first use.

I'm sure there are a few other language-agnostic concepts but these are the first few that come to mind. As far as I know, it's relatively difficult to discuss coding standards in absence of a specific language. And I concur with the other replies above--the best style is usually the one that most seamlessly blends with the existing style.

You may want to take a look at Steve McConnell's Code Complete. It's full of good ideas that should be applicable in almost any development situation regardless of programming language.

Answer 6

One of the great standards we have is variable "prefixing". Until I came here, I'd mostly written solo so I didn't worry about it.

We're "required" to name variables with prefixes that indicate what they are. So, you know instantly when looking at dpVarName that it's a pointer to a double, and that lVarName is a long int.

I was glad at first that they gave us two choices for bracketing blocks, but now I wish we were all just forced to do it one way or the other.