Wednesday, January 11, 2012

Coding Guidelines

If you can't get past the paywall to this article


Coding Guidelines: Finding the Art in the Science
Robert Green, Henry Ledgard, Communications of the ACM, December 2011

then try this version:

Professional coding guidelines
Ledgard, H., 2011 Unpublished report, University of Toledo

There's lots of good stuff, most of which I agree with, like making names pronounceable and using vertical alignment.

The comments about comments, however, seem a bit shallow, especially in the CACM article: examples of poorly-written comments in poorly-written code are used to conclude that comments should be avoided. The opposite is true: well-written comments are enormously helpful in explaining the "what" and "why" of a piece of code; no matter how readable the code is it only presents the "how".

Comments have other uses, sometimes historical: documenting as-yet-unsolved bugs, explaining why some unexpected or unusual change was made, even explaining why some change was not made.

To put this information anywhere other than in the code itself is to guarantee future maintenance programmers will never read it.


2 comments:

Anonymous said...

vertical alignment looks good, but it's hard to use this code style without special automatic code editor tool. So, in my practice I am never use it :(

P.S.
open Id from livejournal doesn't work.

Anonymous said...

I recently discovered a really good philosophy about comments. I started tutoring a high-school student long-distance. When I provide code samples to him, I have to include comments that teach the student what the code means. Well, that's exactly what I need myself when I look at any of my old code...