[thelist] Coding standards....

Brooking, John John.Brooking at sappi.com
Fri Dec 8 08:51:09 CST 2006

My two cents:

> Comment how? Are you talking about inline comments or block comments
> at the beginning of classes/programs/procedures/functions/etc? How
> should I format my block comments? jsdoc format? Dont care? etc.

> With large and complex HTML element nesting I find comments on end
> are very useful. 

To extend the last recommendation to code in general, I find it
extremely helpful is to follow an end-brace with a short comment
describing what it's closing, if the matching begin-brace is more than a
half dozen lines up. For instance, "} // for each $arrFoo" or "} // if
logged in". (Use in very short sections, however, is not really
necessary and just makes things look cluttered.)

> Tangentially, ensure you have some version control in place.
> w/TortoiseSVN etc is great on Windows. Even in a one developer shop
> very useful.

Some version control software allows you to put keywords into your
comments which expand automatically, so you can track the version
number, last modified date and author, etc. One of my favorite uses of
this is a log feature, where all the comments that were typed into the
version control software describing the changes when they are checked in
are automatically inserted into your code. That way you don't have to
manually maintain change descriptions at the top, which I've found most
people don't bother doing over the long term anyway. QVCS by Qumasoft is
one VC application I've used which has this feature. (I am not
affiliated with Qumasoft except as a satisfied customer.) It also allows
you to specify just the last N version comments, so that if your module
has gone through 20 versions, you don't have to have all 20 change
descriptions taking up the first 5 screens of code, just the most recent
3 or 4 or whatever N you choose. Of course you still have the full 20
descriptions in your change control software if you need to see them.

- John

This message may contain information which is private, privileged or confidential and is intended solely for the use of the individual or entity named in the message. If you are not the intended recipient of this message, please notify the sender thereof and destroy / delete the message. Neither the sender nor Sappi Limited (including its subsidiaries and associated companies) shall incur any liability resulting directly or indirectly from accessing any of the attached files which may contain a virus or the like.

More information about the thelist mailing list