If you can't get past the paywall to this article
then try this version:
Coding Guidelines: Finding the Art in the Science
Robert Green, Henry Ledgard, Communications of the ACM, December 2011
There's lots of good stuff, most of which I agree with, like making names pronounceable and using vertical alignment.
Professional coding guidelinesLedgard, H., 2011 Unpublished report, University of Toledo
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:
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.
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...
Post a Comment