How to Comment Code

By Deane Barker on February 11, 2009

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.

Gadgetopia
What Links Here

Comments

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

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

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

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

Comments are closed. If you have something you really want to say, email editors@gadgetopia.com and we‘ll get it added for you.