NOTICE:
This content is in the "archives" of Gadgetopia. It has been moved to this subdomain as it is no longer considered relevant to the site. It is being hosted here for a indeterminate period of time. Its existence at this URL is not guaranteed, and it may be removed at any time. If you would like to refer to this content in the future, you are encouraged to save it to your local file system.

How to Comment Code

Originally published by "dbarker" on 2009-02-11 14:56:00Z

The How, Not the Why: The Code SOD over at the Daily WTF today demonstrates something I’m crazy guilty of.

Why write comments that describe nothing more than exactly what the following line of code does? Why, why, why?!

I do this all the time. In fact, that code sample could have very easily been one of mine. I comment just for the sake of commenting, when a split-second review of the code would reveal the same thing.

When you really need a comment is when you do something that isn’t obvious on first glance. Comments in those situations are the really critical thing.

Comment by "Brooks" on 2009-02-11 17:35:00Z
Well, it's a good thing we can all agree on what's obvious at first glance. Otherwise, this argument wouldn't make any sense at all. I'll just go back to not commenting my SQL stored procedures that join 30+ tables, since to a guy like me who's worked on this same database for almost 10 years, they're all exceedingly obvious.
Comment by "Peter" on 2009-02-12 13:54:00Z
Transmission t = new Transmission(); t.setSelector(Transmission.DRIVE); // because I want to move the car forward obvious at first glance, but a second person who knows your intentions may come up with a different howto.
Comment by "Peter" on 2009-02-15 17:07:00Z
I think commenting obvious lines came from an educational discipline.... so that the person grading the student's program will have a better idea how well the students are doing..
Comment by "benxamin" on 2009-02-16 15:24:00Z
I like Peter's last comment. This weekend, I attempted to explain some code to my brother (doesn't know syntax of anything), and mercifully, I had every section commented. This made it much less frustrating.