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

Why I comment code...

[Saeed al-Sahaf]

I don't know why people (in general) don't like to comment code. I comment mostly for me, so a year or two down the line I'll know why I did something (I've found over the years of writing code, I may think I'll remember, but that often does not end up the case). In the end this selfish purpose ends up helping when other people need to maintain my code (other people fucking around with my code? Never).

What makes a good Comment?

[vivin]

Good comments should explain these areas:

a) What you're doing.
b) Why you're doing it.
c) How you're doing it.

I took three assembly programming classes in College. The last one was on the 68k, where we wrote an embedded OS.

Assembly code isn't all that intuitive, and writing comments is especially important. Our professor allocated 20% of our grade on each lab to comments. In addition to accurately describing what we were doing, he checked our grammar. One thing he always stressed is that too many engineers these days don't know how to write comments. Grammar is important in getting the message across unambiguously.

In general, if a person can read your comment and then figure out how to translate what you said into code, then your comment is pretty good. It should give an idea of what you're trying to do, why you're doing it, and how you're doing it.

One of my professor's grad students translated a program from MACRO32 into C++, and all without even knowing MACRO32. He looked through the comments to figure out what they were doing. They were so specific that he could easily translate blocks of code over to C++.

Comments are very important - and I should definitely comment MY code. I can't remember the number of times I've come back to code that I've written and thought "WTF am I doing here? WTF was I smoking when I wrote this?!"

Re:My favorite code comment not written by me

[Abcd1234]

Well, there's nothing wrong with entertaining comments, as long as that's not *all* you have. In my experience, useful comments interspersed with a bit of humour can make code analysis and maintenence at least a little less boring.

Re:Comments are more important than Code?

[Not_Wiggins]

Actually, I start my programming projects by writing all the comments first; in this way, I get the pseudo-code ideas down and write the associated code under each comment. It helps me track where I am in a class/function, what I'm trying to accomplish (what parts still need to be written), and it nicely leaves an understandable trail without having to back-fill the code with comments once the project is "done."

By front-loading the process with comments, I find it really helps not just the maintainability but it also keeps my programming tasks on track.