Successful Strategies for Commenting Your Code

LilG writes "Over at Particletree, Ryan Campbell writes about Successful Strategies for Commenting Your Code. His essay gives advice and examples on proper commenting, and details some different strategies."

Comments

really being stressed in schools

[StarvingSE]

The next generation of professional coders will most likely be good commenters as well. I know from experience in my computer science classes, professors will mark programming assignments down significantly if comments are not included, or if they are hard to read. Most of the time they want all functions to be commented to explain what their parameters mean, how the function works, and the format of the output.

Re:Don't do it!

[1nt3lx]

This works quite well, but there are some consequences for this action:

1. You are likely to be passed by on promotions because self inflicted developer dependence for this application.
2. You will have to figure it out later, after you've forgotten what all that magic gobly-gook does.

magic gobly-gook: effective, efficient, and incredibly dense code produced wilst 'in the zone'

Re:What makes a good Comment?

[idontgno]

As long as you're commenting the _real_ effect of the instruction, and not just mindlessly repeating what the mnemonic already tells the reader.

Or worse yet, lying.

One pre-paleolithic piece of mainframe assembler I (and my colleagues) once worked with was an intricate sequence of shift operations designed to isolate a 5-bit segment in the middle of a 36-bit word in one of the accumulators. It was documented with a breathtakingly detailed block of comments, complete with little pictures of the contents of the register at each step in the process (composed of dashes and vertical bars and everything--ASCII documentation art).

The code wasn't working, but there was absolutely no way that it was the code's fault. It was just FM (F'ing Magic) that it was broke. We were convinced of this. That is, until one of my supervisors, a crusty old communications sergeant, actually studied the instruction string of the segement of code in question and noticed that in the last step, the actual answer was being shifted the wrong direction--right out of the register and into the bit bucket.

If only we could have compiled the comments...

This, then, is Johnson's Postulate on Documentation: "Read the source code, too."