Putting Comments in Code

During my career as a technical writer, I've had to document several APIs in a variety of languages. At Daleen Technologies, we sold the API as part of the product, and I had to learn Java so I could add and edit comments directly in the code. I learned a lot about what to do, and more importantly, what not to do, thanks to some helpful (and occasionally exasperated) developers.

This article by Bill Sourour would have been extremely helpful when I was starting out.

Stop me if you’ve heard this one before…

“Good code is self-documenting.”

In 20+ years of writing code for a living, this is the one phrase I’ve heard the most.

It’s cliché.

And like many clichés, it has a kernel of truth to it. But this truth has been so abused that most people who utter the phrase have no idea what it really means.

Is it true? Yes.

Does it mean you should never comment your code? No.

In this article we’ll look at the good, the bad, and the ugly when it comes to commenting your code.

For starters, there are really two different types of code comments. I call them documentation comments and clarification comments.