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."

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:really being stressed in schools

[j-tull]

As one who has graded many undergraduate programming assignments I can tell you that professors very seldom actually read, let alone provide feedback on, comments. Comments on assignments tend to be scored as, "Are they there? If yes, good! If not, -10 pts for being a dumb ass."

Summary: Though the next generation of coders may be more diligent about including comments (at least initially -- though I'm not sure I'm even convinced on this point), there is nothing that leads me to believe the content and appropriateness of their comments will be any better than what we see today.

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:indeed

[B'Trey]

There are two problems with this.

The first is that common sense isn't. There are lots of coders who seem not to have any.

Second, what seems clear and obvious when you're writing the code is anything but to someone else who's approaching the code fresh. That "someone else" may very well be you six months or a year down the road. Every function over one line (and most of those) should have a comment indicating what it does. Any variable that isn't a throwaway loop counter or similar should either be so clearly named that your grandmother could tell you what it's used for or be commented. Etc.

It takes seconds or minutes to write comments. One comment can save you hours of time and loads of frustration. Common sense says to write the comments, even if you don't think you'll need them. You only need to be wrong once or twice to come out ahead.

doxygen

[Wescotte]

You still need to know how to write good comments but I find using doxygen is a great tool for generating useful documentation directly from comments in your code. If you haven't heard of it give it a shot.

http://www.stack.nl/~dimitri/doxygen/ [stack.nl] Doxygen homepage.

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."

Re:What makes a good Comment?

[lebow]

Ok well there is sometimes a reason I've found to do this. I come in in the middle of a project where some one wrote a bunch of poorly designed functions, that don't take arguments ( data is passed through global vars ) and they produce a extremely specific result that should be more general. for example fetchdata() a highly specific function with a generic name. I want to write a real fetchdata() that is generic and I can use in other parts of the code but the good name is already taken, and I don't have the patience ( or time ) to go through and fix it every where in the whole project. ( I guess I could do a global search and replace but.. )

So I make fetchdata2() ( or fetchdata_good() and use that from now on and when I can try to replace the old fetchdata()s to use the better version.