Good article Pam!

I'm with Jeff on the issue of comments though.  If you *have* to put comments to tell *what* you did, it's either very complex or poorly designed.  But that doesn't mean you should leave them out.  "Obvious" comments are helpful to junior developers to whom the code will be less obvious.  They often do not understand why one approach was taken instead of another and they're often tasked with maintaining older code long before they get to write new code.  Comments are a great teaching tool.

Comments explaining *why* you did something are needed in every block except the most trivial.  You can't determine why something was done by looking at code.  You can guess, and you might even guess correctly, but you can never be certain because the code only shows the implementation or the *how* something was done.  Comments tell the full story and tie the code to the business process.

If you extract just the comments from my code you will be able to see what and why my code does what it does.  In fact, I usually write the comments as pseudocode before I ever code the statement itself.

And shame on the developer who doesn't update their comments when they update their code.  That's sloppy development and is not excusable.