CodeBetter.Com
CodeBetter.Com
RSS 2.0 via Feedburner
           Do you Twitter? Follow us @CodeBetter

Darrell Norton's Blog [MVP]

Fill in description here...

Coding standards

Roy Osherove posts about coding standards, referencing DotNetJunkies own blogger Mark Brown, who posted about IDesign.net's C# Coding Standards.  When I was working on creating coding standards for my company, I also looked at Mike Kruger's C# coding standard, the Code Conventions for the Java Programming Language, and Scott Ambler's Coding Standards for Java.

Roy makes some good points, like make sure all employees agree with the standards, consult with everyone (a way to build consensus and buy-in), and the comment that "no one will bother adhering to a 250 page document."  IDesign's coding standard is only 20 pages long, but even that is pushing it.  If developers have to keep referencing the document to follow the "finer points" of coding style, it will always be rejected.  Ideally, only those things which can be automatically detected (through something like FxCop) should be part of the coding standard.  FxCop allows a developer to check their conformance to "standards" continuously, and it even offers explanations on how to change "offending" code and why. You can also develop your own in-house rules. I would like to caution that "Merely saying 'make it so' doesn't make it so."

As you develop a coding standard, remember that new employees will get the full hockey stick part of the learning curve, whereas you will be able to assimilate a few pieces at a time.  New employees take a long time to become productive employees and salaries are the biggest expense for any consulting/software development firm, so you want to make it as easy as possible for them to get up to speed.  You do not want to create additional artificial barriers that prevent employees from being productive.  The key is to balance the improved readability of code with the increased learning curve for new hires.  Some agile developers get along very well with a coding standard that consists of "The code must be readable and understandable at a glance."

One thing that irks me about IDesign's coding standard is that they specify spaces instead of tabs (on the whole I think the IDesign standard is very good).  Visual Studio .NET can take whatever source code you give it (spaces, tabs, or spaces and tabs) and reformat it according to your preferences by simply highlighting a section and pressing Ctrl-K, Ctrl-F (or go to Edit - Advanced - Format Selection).  There are other options to Tabify, Untabify, and Delete horizontal white space.  Pretty much every IDE will be able to convert spaces and tabs (it is not that difficult a function), so why is this rule there?  It's a waste of space and a waste of time to read.



Comments

Steve said:

Excellent points. I couldn't agree more about making sure the standards are contained in a manageable document.
# July 29, 2003 4:01 AM

Dennis v/d Stelt said:

Excellent points. I couldn't agree more about making sure the standards are contained in a manageable document.
# October 29, 2003 9:56 PM

Dennis v/d Stelt said:

:)
# October 29, 2003 9:56 PM

Scott said:

It's not just IDE support that's required to make the tabs-vs-space rule moot; you also need to make sure that the source control and diff tools you use don't think a line has been meaningfully changed just because your IDE reformatted it.

Great point about the learning curve. I've found that sticking with the most common standards (like Sun's Java standard) makes the most sense since most new employees will be familiar with it.
# November 28, 2003 6:16 AM

Billy said:

Right On!
# March 5, 2004 7:21 AM

Darrell said:

Billy - glad you like. :)
# March 5, 2004 8:01 AM

Darrell said:

Scott - a good diff tool should be able to set the option to ignore whitespace. I know WinMerge does, and so does Beyond Compare. And if the diff tool doesn't support it, maybe you can replace it with a better tool.
# March 5, 2004 8:02 AM

Darrell said:

Steve - fewer rough-cut rules that are followed are better than many perfect rules that are not.
# March 5, 2004 8:03 AM

Ramesh said:

Is it a 25 page document or 250 page document?
# June 2, 2004 12:08 AM

Darrell said:

My coding standard document was 18 pages, which included code samples! :)
# June 2, 2004 1:41 AM

Mike said:

I agree with IDesign's "spaces not tabs" standard. My main reason is that even if a standard specifies tabs, most code will contain a mix of tabs and spaces because developers will use the tab key and press the space bar a few times to "line up" something like a multi-line parameter list for example. And the main problem with mixing tabs and spaces, is that now the code will look all jumbled should you be viewing it with different tab stop settings. For example, the WinDiff, SourceSafe diff, and notepad often have tabstop settings that aren't the same as in VisualStudio. In a perfect world, there shouldn't be a difference between a "spaces only" and a "tabs only" standard...it should be a coin-toss, however, since it is neigh impossible in a "tabs only" standard to actually have only tabs in the code base, the better solution from my perspective is the "spaces only" standard. That's my long winded reason why I agree with IDesgin. cheerio!
# December 7, 2004 11:41 AM

Darrell said:

Sounds good, Mike. I'm still debating on whether to use spaces or tabs. I haven't run into any problems with my teammates yet, so we'll see.
# December 7, 2004 12:05 PM
Check out Devlicio.us!