A Dearth of Comments

Question

A Dearth of Comments

Steve Jones - SSC Editor

SSC Guru

Points: 735195
More actions
January 26, 2010 at 8:46 pm

#63603

Comments posted to this topic are about the item A Dearth of Comments

Viewing 4 posts - 1 through 3 (of 3 total)

You must be logged in to reply to this topic. Login to reply

Jeff Moden SSC Guru Points: 1004053 More actions · Answer 1

I definitely agree that some prior knowledge is essential when reading another person's comments in code.

However, I've found that a lot of folks either don't comment enough, don't know how to comment, or simply don't make any comments at all. An example of "don't know how to comment" is when someone writes a comment like "Updates the address table". Yep... we can figure that out. What we might not be able to figure out is the "why". Why does the address table need to be updated? The comment doesn't need to be long... "Update the customers' mailing address with the the latest address from today's import."

I'm not sure why some folks are so adverse to writing a comment for each Insert, Select, Update, or Delete and that includes a separate comment for each sub-query or CTE. Perhaps it's because people no longer write process charts or flow charts to keep track of what they're doing. For me, it's easy... before I write the next Insert, Select, Update, or Delete in any given T-SQL code, I'll look at the requirements (if any are provided) or my notes on what needs to be done and simply write down what I need to do in the code as comments. Then I write the code under that comment. It also helps me stay focused on just what it is I'm supposed to make the code do. Any "tricky" or "not so obvious" code get's an extra dose of "how" to go along with the "why".

We did a bit of a test at one of my previous companies concerning comments. We gave several developers all the same code with all the same requirements to modify the code. The only difference was that some developers got the original code that had very sparse commenting and the others got code that had the type of commenting that I said I write above. The modifications required in the code were fairly substantial. The developers that got the sparsely commented code took an average of 2 FTE days to do the necessary research just to begin writing the modifications. The developers that got the fully commented code took an average of only 2 hours to do the necessary research.

It didn't stop there, either. The developers that modified the sparsely commented code had a much higher failure rate in QA than the developers with the fully commented code even though they were operating on otherwise identical code from identical printed requirements.

It actually takes almost zero effort to write comments in code as you go. I believe there are two major reasons why developers don't take the time to do it. 1) It's not taught or it's not taught well. In fact, many developers follow or have been taught the mantra of "you can read the code to figure it out because of the names of the objects". 2) Developers are under the gun to "perform". A lot of managers simply don't care about comments because they either don't know the comments aren't being included or they haven't been taught their value, either. No matter the reason, the perception is that writing comments will slow you down and in order to be perceived as a "high performer", comments are simply skipped.

I really think that perception is terribly wrong. If you remove all the code from my stored procs (or my forum posts, for that matter), you could build a process or functional flow chart from the comments that remain. Does it take me longer? Sure... about 5 minutes out of an hour. In the short run, comments actually do save me time. I get interupted a lot and because I write a short comment about what I need to do and why, I never have to turn back to the machine after being interupted and ask, "Ok, now where the heck was I?"

As a side bar... comments are difficult to separate from the code and are not easily lost. Updating comments after a modification is the same process as writing new code... write or rewrite the comment with the new requirement first. It just doesn't take that long to do and the long term benefits have a huge payback whenever any rework is required.

"Make it work, make it fast, make it pretty... and it ain't done 'til it's pretty." 😉

--Jeff Moden

RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

Change is inevitable... Change for the better is not.

Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)

Steve Jones - SSC Editor SSC Guru Points: 735195 More actions · Answer 2

I think you've moved my mind a little on this, Jeff. I have avoided simple comments for years, often because it does seem to waste time to me. However, a short comment would not really take much time, and it would probably help someone to get in the zone of following the process, not to mention it would ensure that I was thinking through the process and requirements correctly.

Heck, it might even prevent or stimulate a test or two to see if my results matched the comment.

Now if I could just learn to type "short" comments, I'd be in good shape.

Jeff Moden SSC Guru Points: 1004053 More actions · Answer 3

Thanks for the feedback, Steve.

--Jeff Moden

RBAR is pronounced "ree-bar" and is a "Modenism" for Row-By-Agonizing-Row.
First step towards the paradigm shift of writing Set Based code:
________Stop thinking about what you want to do to a ROW... think, instead, of what you want to do to a COLUMN.

Change is inevitable... Change for the better is not.

Helpful Links:
How to post code problems
How to Post Performance Problems
Create a Tally Function (fnTally)