Worst Practice - Bad Comments

Question

Post reply

Worst Practice - Bad Comments

Viewing 8 posts - 31 through 37 (of 37 total)

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

mcroswait SSC Rookie Points: 43 More actions · Answer 1

quote:
Just think of the fun you'll have with that!

At least I have some background with *nix... our developers are REALLY having fun!!!

AJ Ahrens SSC-Insane Points: 20676 More actions · Answer 2

I have inherited a system that has NO comments in it whatsoever. I have added comments as I modify the procedures and have to spend a lot of time researching WHY things happen the way they do.

I also have a problem with development REFUSING to document the changes. I have brought the value of comments to both my management and their management and their management has determined comments are not needed. Makes my life even worse. Try getting them to use CAPITILIZATION too..

Thanks for letting me vent

AJ Ahrens

SQL DBA

Custom Billing AT&T Labs

Good Hunting!

AJ Ahrens

webmaster@kritter.net

wodom Hall of Fame Points: 3813 More actions · Answer 3

Tell them telephones aren't needed either, but they sure do save a lot of time & money. And THEY cost a LOT more than comments.

cwedgwood50 SSCommitted Points: 1751 More actions · Answer 4

On commenting in general(not just TSQL);

I think well written, self descriptive code is the most important thing. Every effort should be made to get this right, indents, readable variable names etc.. Then comments to highlight important information that is not obvious from the code. Comments are exceptionally useful, but only when used sparingly, unless teaching code. The fewer comments there are the less chance that future changes will result in comments becoming inadvertantly out-of-sync with the code. I do like a header block at the top though, but think info like last modified should be derived from file save date rather than a comment. It only takes one sloppy programmer to make a change and not comment and that information is wrong!

steven powell Mr or Mrs. 500 Points: 557 More actions · Answer 5

One example i came across this week was a lengthy, descriptive and very helpful comment, which related to an old version of the code and as a result was completely meaningless and could've sent me down the wrong path for hours. In this case the comment was far worse than

--select * from table1

sqltimd SSC Enthusiast Points: 109 More actions · Answer 6

In terms of header comments, I don't think I could survive without them. Even on smaller projects, where I'm the only developer, they tend to come in handy. If I have to work on a stored procedure that I wrote several months back, there's a good chance that I won't remember exactly what the sproc does. The header is a good way to "get up to speed" quickly. And for projects where several developers are involved, the "history" section of the header (who changed what, why, and when) can really come in handy.

As for commenting in general, I guess I tend to think that there's no such thing as "too many" comments. And I probably leave my fair share of what you'd call meaningless (or redundant) comments as well. And here's why: When I first start development of a stored procedure, I write meta code in the form of comments. I basically outline everything that I think the procedure is going to have to do to accomplish the task. Once the meta code is finished, I take a second pass and add the actual TSQL code.

chrisleonard SSCertifiable Points: 5030 More actions · Answer 7

My favorite teaching example of a useless comment follows:

Useless comment:
/* Divide @nh by @nab, storing result in @bav: */
SELECT @bav = @nh / @nab
Better comment:
/* Calculate batting average: */
SELECT @bav = @nh / @nab

Granted, this is a "loaded" example, since the variable names are not descriptive, but it illustrates one other issue with comments: focus on process, not syntax. In other words, one specific form of a useless comment is one that assumes that the reader can't read whatever language you're programming in.

I do think that script header comments serve a good purpose, as someone posted earlier. Not only can you include usage information (I know someone who does this with extended properties, by the way - a nifty idea), but you can "self-document" things like the location of the source file and the change history. All of this information is useful when you need to change the proc - the usage info gives a sanity check to make sure you know the purpose of the proc, the source location lets you know where to get the code you need to change, and the change history lets you find the idiot whose code you can't understand - or at least realize (with sudden humility) that the idiot is actually YOU.

Interesting post. I had to write a couple pages on comments once for an Exam Cram book (remember those? the first series of them, I mean...). Two pages was all I could come up with. I pulled a copy off of the shelf just for grins, and I can't see anything else I put in there that's not just newbie information...

Chris

John Scarborough Ten Centuries Points: 1104 More actions · Answer 8

"Bad" commenting is the least of my worries. Holy cow.. I'm trying to get these people to comment at all! I'm darned sure not going to complain about how they comment!

John Scarborough
MCDBA, MCSA