I posted this link for my VB class and got some decent thoughts back, so I figured I’d share with you all, too.
Just throwing this perspective piece out there for your consideration: The art of commenting: Is commenting your code a waste of time, or programmer gold? By Brian MacDonald.
One of the things I noticed while trying to pick up programming on my own was the number of off the cuff “should be”s that get thrown out with no real context and no real idea of what the implementation of those “should be”s would look like. For this particular “should be” (“code should be commented”), I think the article author provides some decent guidelines of what he means by commenting your code.
And for a contrary view, linked to in “The art of commenting”: Why You Shouldn’t Comment (or Document) Code, by Peter Vogel, with a follow up to clarify points in the main article: No Comment: Why Commenting Code Is Still a Bad Idea
At the time I’m posting this, there was a typo (I’m guessing) in the last comment pictured in “The art of commenting” article. I thought that kind of (but not really that much) supported Vogel’s point.
One of my classmates pointed out that Vogel references a book written in 1978, and at the time that book was current, Bill Gate’s BASIC Interpreter was 8KB, and still bigger than the system RAM on most microcomputers. Given that kind of memory premium, and the cost of computing resources, it makes a lot of sense that back then, code commenting had a serious, immediate real dollar impact.
The immediate cost of commenting is now minimal with the drop in hardware costs, so the debate is now focused on more abstracted costs: time and frustration. (Could you argue that time is an immediate cost? Yeah, but! The time cost can play to both sides, depending on the context).
Ultimately, I fall on commenting more extensively, for now, for a few reasons:
- I like working myself out of a job. Once I’m done with a project I like to be done with it and not get pulled back into redoing it, over and over again.
- When I do get pulled back into a project, I like being able to pick up where I left off, without having to hack my brain figuring out the same problem I figured out the first time through.
- I like being able to skim the code I’ve written before to see if I already figured out a problem similar to the one I’m working on. Notice I said “skim”.
- With tools like JavaDocs and Doxygen, you gain productivity boosts by commenting your source code. (More about documentation here)
- I use the comments, especially with JavaDocs, to think my way through what I need to code before I write my code. It’s just easier for me to spot problems in methodology and logic in natural human language than in a programming language.