Coding Standard

The main decisions

Here are the main areas where people on a team often have different preferences and might need to agree on something. It's hard to argue that any one system has a huge advantage over any other system. But consistency on some of these things has a big advantage over inconsistency: everyone on a team can read code easily and make parts of the system refer to other parts of the system easily.

1. Naming convention

Bumpy Case or underscores?

Bumpy Case has the advantage that DueDate is clearly a class while dueDate is clearly an instance. Bumpy Case also makes individual program statements a little shorter and less likely to wrap across multiple lines.

Do we indicate the type of identifiers in how we choose their name?

A common system is:

The name of a subroutine is usually clear from context since it's followed by parentheses. At the opposite end of the spectrum, Hungarian Notation embeds a lot more type information in a name.

Any special way of indicating data members or private members?

Some people use a prefix, like _ or m_:

In non-OO languages, where you have to fake classes, how do you create the fake namespace for a class?

A common solution is to combine Bumpy Case and underscores, like this:

Do you name an array after the singular or the plural of the kind of element it contains?

or:

Using the plural has the advantage that you can write code like this:

or in Python Language:

2. Where do you put the braces?

In other words, like this: (Lisp- / Smalltalk-style)

or like this:

or like this:

or like this:

or like this:

or like this (actually spotted it somewhere, but don't remember):

Similar questions need to be asked for any multiple-line construction with delimiters; for example, a function declaration with arguments that (for whatever reason) should be split over several lines:

or

or

or

or

3. Indentation

Indentation of 2 columns or more than 4 columns tends to be hard to read. An advantage of 3-column indentation over 4-column is that while both are readable, 3-column indentation makes shorter lines that are less likely to go past 80 columns and wrap.

In some languages, like Cascading Style Sheets, 2 columns can actually be more readable.

4. Tabs

Do you include tabs (ASCII 9) in your source files or not? Each tab represents one level of indentation.

If you include tabs in your source files, then everyone can set their editor to expand tabs to however many spaces they like.

Except not really, since people insert a different number of tabs to make things line up depending on the tab setting.

Vi Editor and others can be set ("set expandtab") to automatically convert the tab keystroke into the appropriate number of spaces. When indentations are stored as spaces, program code is readable in gdb, on a printer, in email, etc. In those places, the tab character expands to 8 spaces, causing code with one tab per indentation to spread out so much that it's almost unreadable.

Python Language requires consistency of tabs and spaces, so it almost mandates the "expandtab" approach.

5. Type on same line as function definition?

Like this:

or like this:

The first way has the advantage that tools (like ctags) can easily find the beginnings of functions, since the function name always occurs at the beginning of the line.

Has anyone else here ever tried to produce a Coding Standard document? The time and level of detail make this a difficult thing to accomplish, and when you are done, there is the issue of convincing people to actually follow it. I am beginning to doubt that a Coding Standard provides more value that it costs. Would anyone care to describe some first hand experience in the development and use of Coding Standards? -- Wayne Mack

An easy way to do it is on a wiki, gradually, illustrated by simple examples, not in some huge session where everyone argues against everyone else. The Coding Standard will mostly grow out of conversations that happen while Pair Programming. When you run into a specific problem that a Coding Standard can solve, solve it then.

Long ago, in a company far away, Leo Scott created a coding standard of a very few lines. I think it fit on the first half of a double-spaced page. I'll see if he still has a copy of it so I can post it here. The rules I remember most were something like:

No tabs

Braces line up

No tabs

No returns out of the middle

No tabs

There is noooooo... rule 6

No rules are absolute

There were a few others. I've since relaxed on most of the rules, and now adhere to them or break them more or less willy-nilly, in a way that must drive my coworkers nuts. But I still don't care much for tabs and often leave out rule 6.

Anyhow, it being a very short standard was part of what made it work. At the very least, its diminutive size limited the number of official-things-to-fight-about (which, in a way, is what a coding standard often ends up being).

What embarrasses me now is the number of good programmers I pissed off with my small-minded insistence upon adherence to rules which now seem rather stupid to me. -- Wayne Conrad

Wayne did a great job on my coding "un"standard. I think I had one more rule that said "No GOTOs". I have never been a fan of coding standards, but in the past I could see why people wanted them. It is interesting that the more XP that I do, the more I come to see that coding standards are just one way to deal with problem code. All the ugly, hard to read, hard to modify code can be dealt with either with a set of rules (i.e. coding standards) or a set of principles (XP ideas like refactoring, do the simplest thing possible, YAGNI, pairs, etc). I find that there are still three or four things you want the team to agree on, then just following XP principles naturally produces beautiful, easy to read, easy to change code that conforms to the most nit-picky coding standards. After all, most of the problems in code that coding standards are trying to fix are not a problem when Test First Design pushes you in the direction of methods that are named for what they do, do only one thing and are only 2 to 10 lines long. And if they're not, the next pair refactors them.

Coding standards try to defend against bad code - XP tries to create good code and constantly make it better -- Leo Scott

This (from the Infospheres templates document) is a degenerate case for what happens when you have all these coding standards which aren't really solving a genuine problem:

This snippet is about 50% comments, it has the required constructor comment, and it doesn't do anything.

Couldn't you just write something like:

instead? -- Mike Smith

I remember reading some Java Doc guidelines that mentioned the problem of how coders who fill in all the required fields often give redundant information that could be gleaned from the code alone -- I mean the pieces of code that are included in the Java Doc, e.g. variable names. They said that of course you shouldn't introduce mindless redundancy, but rather try to provide a description that contains more information. Personally, I treat almost every place for a potential Java Doc comment as optional; the Java Doc utility doesn't really complain :-) Consider

This would hardly benefit from a comment saying

Of course, you could provide more information by using the terms abscissa and ordinate in the comments for getX() and getY() respectively, instead of repeating the names x and y. A nice way of reminding the reader of which is which. However, it only makes sense if this isn't mentioned already in the description of the class and if these terms are actually used elsewhere in the program/documentation. A compromise I often employ is to provide only the @return clause.

As you see, in practise all redundant/superfluous (parts of) Java Doc comments can be safely omitted and nothing bad will happen. The problem with this is that you can hardly write a Coding Standard around such terms, because then everyone would just invent his/her own definition of "redundant", "superfluous" etc. and procede as he/she pleases. I guess this is the reason why so many 'fields' were declared required in the first place. -- Ne Ks

Even the redundant types of javadocs are valuable if one does not have access to the source code and the javadoc is the only available documentation, however.

Would anyone care to describe some first hand experience in the development and use of Coding Standards?

I've tried several times to type up a coding standard document that formalized what the team already did automatically. Each time, I've given up when I realized that it was too much work to think of all the possibilities. Oral Tradition worked so much better.

On my last project, though, I was leaving the project and wanted those who followed us to know what our Coding Standards had been. Eventually I came up with this:

Style guide

We don't have a formal style guide. But we do think that a consistent style is important. We have thousands of lines of code -- as you write new code, take a look at what we've done before and try to match it.

Here's some hints to help you get started:

Our code is mostly consistent with Sun's Java style guide.

Acronyms are considered words. Only the first letter is ever capitalized.

When breaking a statement across multiple lines, we only indent and outdent two spaces at a time.

We use spaces rather than tabs in our source code so that it renders consistently.

We also have some design conventions:

We don't like to pass null references around.

When an exception occurs, we either resolve the problem or we propagate the exception. We very rarely catch an exception and then do nothing with it; when we do, it's for a good reason (which we document).

We don't log errors -- we send an email and inform someone that a problem has occurred. Sometimes we log and send an email; the point is that our code is proactive about problems.

That's it. Unfortunately, I can't tell you if it's a good style guide or not, since to my knowledge, nobody ever read it. On future projects, though, I would probably use that as a starting point.

On an earlier project, we had a discussion early on about style. I declared that, since I didn't want style to become a divisive issue, any style was okay as long as the code communicated well. We ended up with many different styles, including three different brace styles, often within the same class. It worked fine. Coding standards are overrated. -- Jim Little

William Wake's single-page standard recommends catching all Exceptions in the finally{} block, which works fine if an exception is thrown in the try{} block. It will not work as expected if the try{} block completes normally but then there is an error in resource release. If so, the generated exception is swallowed.

It might be fun to make a coding standard that makes the code on a page look like a two dimensional picture, with each page having a sort of 'look' about it that would help readers identify its function. A Two Dimensional Coding standard could be rather fun.

I use a variant of the "Spaces, not tabs" rule, which specifies monospaced font (critical for ASCII-art diagrams ;-), 8-column tab stops, and strict space/tab equivalence (usually accompanied by a script that detects and prevents tabs in string literals). Forbidding tabs completely in source code (but alas, not Makefiles) looks a lot easier. Who knew tabs could be so annoying?

The only other rules I have ever cared about:

Be locally consistent with indentation and variable names (if they used 4-space-indentation and brace-cuddling in the Foo module but 8-space-indentation, tabs, and no-brace-cuddling in the Bar module, so do you)

Given a choice between two equivalent constructions, pick the one that is less ambiguous to a human reader (so use "(3 * 5) + 7" instead of "3 * 5 + 7").

All style rules are negotiable. Including this one.

IMHO all coding standards should have a specified and specific scope: "for Tcl code on the Foo product" or "for programs that will be built by the Borken Brand Compiler or ported to BorkenOS" or "for sample source code that will be shipped as part of the documentation of our library product."

One coding standard probably can't be sanely applied to 1000 developers using a dozen programming languages, two dozen natural (human) languages, half a dozen toolchains, and uncounted hardware platforms, unless it's extremely long (too long to read) or extremely short (too short to contain any useful information). I try to imagine what a Coding Standard suitable for the Debian project would look like. Even a Coding Standard that handles two different programming languages for a half dozen developers starts to look overly bureaucratic if not downright silly. Shorter is better, the best is as short as possible...but no shorter.

--Zygo Blaxell

On my current contract, we have been able to distill the bulk of our (Java) coding standards into a two-column, single-page Word document. There are a few lines of explicit text, but otherwise the rest of the document demonstrates the standard through code. You do have to do a little reading between the lines.

We spent one hour as a team to run through the contentious points, then drafted an initial standards document. The standard can be reviewed at iteration retrospectives and updated as often as necessary.

One sheet fits nicely onto a wall or the side of a monitor, and after a month or so of adherence it can be removed.

--Jeff Langr

I actually wrote a coding standard for Java. And this was only because I had to, and if it wasn't done by me, it could have been done for the worse. The whole point is to make it minimal. For example I have not specified the alignment of braces so that all following variants are "legal":

Anything that makes the code nicer to read (of course in the subjective judgement of the guy who writes the code), is allowed. Overly restrictive or overly specific coding standards are kind of stupid, IMHO. For example I read in one coding standard that the choice operator ? : should not be used at all. --Costin

I found myself being depressed and starting to make my code sad. It's when I invented Positive Programming.

Here are the rules I found out :

1)Prefer positive first. This makes you not see the bad part of it because it's else

2)Replace negative variable names with positive ones.

More rules to be defined :)

mailto:zimba_AT_@oree.ch

I have just put together a Java coding standards document. Instead of listing hundreds of rules about layout and formatting we just leave that up to an automated tool like Check Style to pick up. The document concentrates on subtler more fundamental standards which rely on the skill of the developer and (importantly) reviewer to enforce.

See Formal Standards, Coding Standard List, Bad Coding Standards, Coding Style, Coding Conventions, Infospheres Coding Standard For Java

It seems to me that the requirement for coding standards stems from the problem of separating layout and content. This has been a huge issue on the web, and is now being addressed by xml, xhtml, and css. Couldn't a similar approach be taken on code? This way everyone can code with a standard that feels natural to them, and everyone else can read the code as they would like it.

IMHO, coding standards only makes sense for pair programming (since otherwise you can use indent and similar tools), and when pair programming, the approach you suggest wouldn't solve anything.

Given further thought, even if it would solve matters of layout (tabs vs. spaces and how many, where does the '{' go?), it would not be able to solve matters such as variable naming conventions.

As you say, this wouldn't be of great use when it comes to pair programming, but improving code readability for others is always a plus. Consider a developer that leaves a project, and all his code is in a written with a very different coding standard. Other developers that wish to pick up where he left off will not be severely hindered by this, but it will be an annoyance.

Why not just run run it through a Pretty Printer, run the full regression tests, then get on with editing it? This also only solves the layout issue, but variable renaming can also be done with a suitable code browser.

Sounds reasonable to me.

A few years ago I put together some white papers on engineering and software design process. One of them covered coding guidelines as a part of the overall process of creating a product. See the papers at www.parsecsystemsinc.com for a distillation of lots of wisdom filtered off this board and other Internet sources.

Note that the coding guidelines include some specifics that I don't particularly like or use myself, but this paper is left over from a project where a buddy of mine was the technical lead. He was in the position of choosing one standard for coding, and we all used what he came up with. That's how it works, you know.

-- Marty Schrader

Coding standards can destroy people's ability to work. I have a significant cognitive deficits in the area of memory and visual tracking. If I am allowed to arrange my code in two dimensions, then my eyes can track it and not get confused by the right hand margins of identifiers, and if is is in two dimension, I can see it all on one screen in front of me at the same time. If I have to scroll I forget immediately what was on the previous page, and if the identifiers are not lined up I spend too much mental energy trying to parse them mentally to understand the program.

For example this works:

This does not:

If the coding standard forces the second kind of program rather than the first, I can't program. -- Jon Grover

Category Coding

See original on c2.com