If you're a coder, you've heard it a thousand times:
"Comment your code."
You might even have worked in an environment that mandates javadoc comments on every function, or worse yet, failed to land a job because your code did not have "enough comments".
I used to be a docs and comments nut, years ago. I was one of the few coders that actually maintained my comments over time.
To get right to the point, experience has shown me that "commenting" is generally a knee-jerk default that is abused as a crutch under the guise of "accepted practice".
I'll let the book Clean Code: A Handbook of Agile Software Craftsmanship, do the talking here. If you're a coder and have never heard of this book...well, you want to do something about that. The chapters on commenting and formatting are very relevant to the new wave of "software metrics" (which personally I see as a way of trying to commoditize the art and practice of coding):
"Usually [comments] are crutches or excuses for poor code or justifications for insufficient decisions."
I find this all to be absolutely true, and not "sort of, sometimes."
To get right to the point, experience has shown me that "commenting" is generally a knee-jerk default that is abused as a crutch under the guise of "accepted practice".
I'll let the book Clean Code: A Handbook of Agile Software Craftsmanship, do the talking here. If you're a coder and have never heard of this book...well, you want to do something about that. The chapters on commenting and formatting are very relevant to the new wave of "software metrics" (which personally I see as a way of trying to commoditize the art and practice of coding):
"There are certainly times when code makes a poor vehicle for explanation. Unfortunately, many programmers have taken this to mean that code is seldom, if ever, a good means for explanation. This is patently false."
"Usually [comments] are crutches or excuses for poor code or justifications for insufficient decisions."
"It is just plain silly to have a rule that says that every function must have a javadoc, or every variable must have a comment."
- Martin, Robert C. (2008-08-01). Clean Code: A Handbook of Agile Software Craftsmanship
I find this all to be absolutely true, and not "sort of, sometimes."
Here's the perfect example. I see this ALL the time regarding event handlers. I do mean ALL the time, at every single organization and contract I've worked for (look at my LinkedIn profile to get an idea of the scope of that statement):
function handleClick ( obj ) { ... }
This coder will be told, in a review or something, "what's it handle exactly?"
The coder will do this:
// This functional handles a click when the user clicks the Submit button
// It accepts the params from the form that the Submit button is part of.
function handleClick ( obj ) { ... }
Hey I did a good job. I added comments to my code to clarify it. Very professional.
Not really. You copped out on the thinking. It's like taking medication for something that could be prevented by exercise.
This is better, because it removes the need for the comment.
function onFormSubmitClick ( formArgs ) { ... }
Should you never comment anything?
Of course not. But a comment, should be considered a temporary compromise; the code is good enough, causes no defects, but isn't easily intelligible with a reasonable amount of perusal. I should probably rethink it when I get a chance, so that I can remove the need for the comment.
So if somebody says to you, "your code doesn't have enough comments," what this more than likely actually means, is that your code is difficult to understand without more comments. Which means it's probably not very well written. Try again.
My final, and favorite, quote from Clean Code:
"The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures."
As always, thanks for visiting.
function handleClick ( obj ) { ... }
This coder will be told, in a review or something, "what's it handle exactly?"
The coder will do this:
// This functional handles a click when the user clicks the Submit button
// It accepts the params from the form that the Submit button is part of.
function handleClick ( obj ) { ... }
Hey I did a good job. I added comments to my code to clarify it. Very professional.
Not really. You copped out on the thinking. It's like taking medication for something that could be prevented by exercise.
This is better, because it removes the need for the comment.
function onFormSubmitClick ( formArgs ) { ... }
Should you never comment anything?
Of course not. But a comment, should be considered a temporary compromise; the code is good enough, causes no defects, but isn't easily intelligible with a reasonable amount of perusal. I should probably rethink it when I get a chance, so that I can remove the need for the comment.
So if somebody says to you, "your code doesn't have enough comments," what this more than likely actually means, is that your code is difficult to understand without more comments. Which means it's probably not very well written. Try again.
My final, and favorite, quote from Clean Code:
"The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures."
As always, thanks for visiting.
