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

BumpyCase or underscores? 

 dueDate or due_date
BumpyCase has the advantage that DueDate is clearly a class while dueDate is clearly an instance. BumpyCase 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: 

 CONSTANT, Class, instance, subroutine.
The name of a subroutine is usually clear from context since it's followed by parentheses. At the opposite end of the spectrum, HungarianNotation 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_: 

 class PhoneNumber {
 private:
    unsigned int m_areaCode;
    unsigned int m_exchange;
    unsigned int m_lastFourDigits;
 public:
    PhoneNumber(string& phoneNumber);
    CallResult call();
    ...
 };
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 BumpyCase and underscores, like this: 

 void MboxParser_create();
 ErrorCode MboxParser_open(char *filename);
 MailHeaderField* MboxParser_getHeaderFields();
Do you name an array after the singular or the plural of the kind of element it contains? 

 MailHeaderField field[]
or: 
 MailHeaderField fields[]
Using the plural has the advantage that you can write code like this: 

 for (int i = 0; i < numFields; i++) {
    MailHeaderField *field = fields[i];
    parse(field);
    // etc.
 }
or in PythonLanguage: 

 for field in fields:
    field.parse()
2. Where do you put the braces?

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

 if (condition) {
    doSomething(); }
or like this: 
 if (condition) {
    doSomething();
 }
or like this: 
 if (condition)
 {
    doSomething();
 }
or like this: 
 if (condition)
   {
     doSomething();
   }
or like this: 
 if (condition)
    {
    doSomething();
    }
or like this (actually spotted it somewhere, but don't remember): 
 if (condition) {
     doSomething();
     }
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: 

 def foo(spam,
         eggs,
         beans):
or 
 def foo(spam,
         eggs,
         beans
 ):
or 
 def foo(spam,
     eggs,
     beans
 ):
or 
 def foo(
     spam,
     eggs,
     beans):
or 
 def foo(
     spam,
     eggs,
     beans
 ):
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 CascadingStyleSheets, 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.

ViEditor 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.

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

5. Type on same line as function definition?

Like this: 

 MailHeaderField*
 MboxParser_getHeaderFields()
 {
    . . .
 }
or like this: 

 MailHeaderField* MboxParser_getHeaderFields()
 {
    . . .
 }
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 CodingStandard 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 CodingStandard provides more value that it costs. Would anyone care to describe some first hand experience in the development and use of CodingStandards? -- WayneMack

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 CodingStandard will mostly grow out of conversations that happen while PairProgramming. When you run into a specific problem that a CodingStandard can solve, solve it then.

Long ago, in a company far away, LeoScott 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:

  1. No tabs
  2. Braces line up
  3. No tabs
  4. No returns out of the middle
  5. No tabs
  6. There is noooooo... rule 6
  7. 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. -- WayneConrad

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 -- LeoScott

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: 

 // Constructors


  /**
   * This is a default constructor. It does nothing of consequence.
   **/


  public JavadocClass()
  {
    super();
  }
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: 

 /** Obligatory default ctor. */
instead? -- MikeSmith

I remember reading some JavaDoc 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 JavaDoc, 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 JavaDoc comment as optional; the JavaDoc utility doesn't really complain :-) Consider 

 int Point.getX() {
return x;
 }
This would hardly benefit from a comment saying 
 /**
  * gets the value of the x coordinate of this Point
  * @return value of x coordinate
  */
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) JavaDoc comments can be safely omitted and nothing bad will happen. The problem with this is that you can hardly write a CodingStandard 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. -- NeKs

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 CodingStandards?

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. OralTradition worked so much better.

On my last project, though, I was leaving the project and wanted those who followed us to know what our CodingStandards 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. -- JimLittle

WilliamWake'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. 

  } finally {
if (out != null) try { out.close(); } catch( Exception ignored) {} }

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 TwoDimensionalCoding 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:

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<tm> Brand Compiler or ported to BorkenOS<tm>" 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 CodingStandard suitable for the Debian project would look like. Even a CodingStandard 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.

--ZygoBlaxell

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.

--JeffLangr

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": 

 if(condition)
 {
   //big block
 }


 if (condition) { shortBlock(); }


 if (condition) { statement1;
                  statement2 ; }
 if (condition) 
     { statement1;
       statement2;
       statement3; }
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 PositiveProgramming?.

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 

 if (happy) then
  ...
 else
  ...


 instead of :


 if (unhappy) then
  ...
 else
  ...
2)Replace negative variable names with positive ones. 

 happy = true
 if (happy) then
  ...


 instead of :


 unhappy = false
 if (not unhappy) then
  ...
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 CheckStyle 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 FormalStandards, CodingStandardList, BadCodingStandards, CodingStyle, CodingConventions, InfospheresCodingStandardForJava

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 PrettyPrinter, 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 http://www.parsecsystemsinc.com/WhitePapers.html 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.

-- MartySchrader

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: 

 consumer.ConsumerFirstName?  = txtFirstName.Text ;
 consumer.ConsumerMiddleName? = txtMiddleName.Text;
 consumer.ConsumerLastName?   = txtLastName.Text  ;
 consumer.CreateDate?         = date              ;
This does not: 

 consumer.ConsumerFirstName? = txtFirstName.Text;
 consumer.ConsumerMiddleName? = txtMiddleName.Text;
 consumer.ConsumerLastName? = txtLastName.Text;
 consumer.CreateDate? = date;
If the coding standard forces the second kind of program rather than the first, I can't program. -- JonGrover

CategoryCoding

EditText of this page (last edited November 24, 2014) or FindPage with title or text search