Coding Styles

This is a religious issue, just like favorite editors, programming languages or operating systems. Coding style guides are also like standards; there are so many to choose some. Here are some for C and C++. There are a few for Java too. Sun publishs one here. There are style guides for most computer languages.

If I have inherited some code that I didn't write (and assuming the original author isn't around to continue maintaining it), then I will reformat it to the coding style that I'm used to (which is close to the common coding conventions). By doing this, I find that I'm able to better understand it. Even though there are tools around to automatically reformat the code, if it's new to me, and I'm expected to be working on it for quite a while, I'll do the reformatting by hand. This allows me to view all the code that makes up a project. Of course there are limits here. The project has to be upto a certain size. I'm certainly not going to reformat the Mozilla code base by hand.

The big exception to this is if I'm contributing bug fixes or enhancements to somebody elses code. I'll respect their style (assume they have a consistent one), no matter how much it differs from mine.

Onto some pet peeves.

• Tabs are evil. Don't use them. You cannot guarantee that one persons tabs are the same size as yours. One of the first things I do is turn all tabs into the correct number of spaces to generate consistent indenting.
• Code created under Windows typically has Control-M's at the end of each line. I find them very distracting when viewed on a Unix system, so I just remove them.
• I'm old enough to have used hand punched cards to program with. Most programmers today are old enough to remembers CRT's with a display of 80 columns. It's a nice line length, yet you see so much code where the line just goes on and on.

  Here's a typical example. I've broken it into two lines for browser formatting, but you get the idea:

        //if (debug){System.out.println("AccessibleDescriptionTest.testUIObject("+
          Debug.describeObject(uiObject)+")");}
  	

  Not only has the programmer used a long line, they've not felt the need to use white space to make it easier to read or modify. It's clear that it's one long line, so that you can easily uncomment it when you need a bit more debugging output. Ugh! Note that this is from a time before the java.util.Logger API came along.

  So I will always try to reformat to a maximum line length of 80 chars.

• Which brings me onto consistency. Use white space to make the code easier to read. Add blank lines to separate sections of code. Pick a style but stick with it. Be consistent.
• Don't put unnecessary comments in your code. One such comment that annoys me is the need to add something to the end brace to indicate what it matches up with. For example.

  	public void testUIObject(Object uiObject) {
              if(debug){System.out.println("ColorChangeTest.continueTest()");}
  	} // testUIObject();
  	

  Most decent editors have a facility to allow you match braces or brackets. You should also consider rewriting your code into smaller functions or methods if you can't make the matching braces visible at the same time in your editor (assuming you aren't trying to read your code on your Palm Pilot).

You should consider using applications such as cstyle or jstyle to help you find places where you can improve the readability of your code. Thanks to Danek Duvall for pointing me at these.

And finally, if you write C code, check out (and obey) the Ten Commandments for C Programmers by Henry Spencer.

[Technorati Tag: Programming]

[Technorati Tag: Coding]

( Jun 22 2004, 01:45:04 PM PDT ) [Listen] Permalink Comments [4]