Derik Whittaker

Syndication

News


Images in this post missing? We recently lost them in a site migration. We're working to restore these as you read this. Should you need an image in an emergency, please contact us at imagehelp@codebetter.com
Some comments are a total waste of time

I am all for comments in code (gasp I know) but some are just a total waste of time.

Case in point.  I came across this today.

/// <summary>
/// Commit Transaction.
/// </summary>
public void CommitTransaction()
{
........
}

WTF, I guess putting the Commit Transaction comment makes it more clear that the method "CommitTransaction' commits a transaction.

As I said above, I am for comments, but I have a few simple rules I like to follow.

  1. Don't repeat yourself
    Like the example above don't waste my time telling me via a comment what the method/property name does when the name of the method/comment clearly states that information.
  2. Comment intent, not logic
    I know how to read if statements, and for loops.  Please do not tell me 'doing a look' or 'doing a check' because that is clear from the code.  However, please tell me why you are doing the loop if it is not obvious.  If there is some funky logic in the loop, that I need to know.
  3. Keep it short, and 'timeless'
    I do not want to read a novel.  I want to read 1 maybe 2 sentences and know enough to move on.
  4. If it is a 'Hack' it needs to be stated as such
    We all have added 'Hacks' to our code.  These are things that would not make sense to the casual observer but there is a reason why they are being done.  THESE MUST BE COMMENTED because if they are not someone else in the future is going to come along and repeat all your mistakes.

Ok, rant over.

Till next time,

BTW, I removed that comment from my code base.


Posted 09-29-2008 3:40 PM by Derik Whittaker
Filed under: ,

[Advertisement]

Comments

Bob Saggett wrote re: Some comments are a total waste of time
on 09-29-2008 6:14 PM

You do realise that that was a documentation comment don't you?

Derik Whittaker wrote re: Some comments are a total waste of time
on 09-29-2008 6:24 PM

@Bob,

Sorry, but not seeing your point.  Regardless of the reason it is waste.  Also, the system does not have 'documentation' comments, nor is any sort of documentation generated from the code base.

It is waste because I took a look to see if there was anything of value there and there was not.

Eber Irigoyen wrote re: Some comments are a total waste of time
on 09-29-2008 6:53 PM

just like twittering: "twittering"

=o)

hnelson wrote re: Some comments are a total waste of time
on 09-29-2008 8:36 PM

With the exception of #4, I would argue (and I don't think I'm alone) that if you need a comment your intent probably isn't clear, and that you might be better off extracting the block in question to its own well-named method.

Dave Ward wrote re: Some comments are a total waste of time
on 09-29-2008 8:46 PM

I think Bob's point was that the comment was likely auto-generated by something like GhostDoc.

Dave Schinkel wrote re: Some comments are a total waste of time
on 09-29-2008 11:31 PM

I totally hate "Hack".  That's the dumbest thing I've seen and I've seen it in Lance Hunt's C# Standards doc.  I hate it.  Why in the world would you put "Hack" in as one of your comments just so you get to find all the "Hacks" in your code.  

Sorry but it just sounds lame and  useless to me.  So during code reviews, we can see that all our code is hacks..hahaha.

I just think it's corny and useless for a HACK comment and just weird.

Dave Schinkel wrote re: Some comments are a total waste of time
on 09-29-2008 11:36 PM

And my standards is at the least, make your comments make sense and use a smart helper tool like GhostDoc.  If  you want to put a Commit Transaction as your comment (I agree with Derik, it's useless), at least explain the params, and the intent for sure in there.  Otherwise you can just see the method name.  That example doesn't tell me a damn thing but just "commit transaction".  Ok WHAT transaction and WHAT TYPE of transation.  

This example is a totally useless XML comment for sure.  It shows laziness on the developer as whole that they did not care enough to make the comment useful/informative, with meaning to it so somebody looking at comments understands what the generic "Commit Transaction" means.  The entire point of comments is to quickly be able to see what each method does but if you do not even give enough descriptive information, there is no point.  You just gave me a generic definition of a method which doesn't do me a damn bit of good for documentation.  You might as well NOT document if you're going to put in something this useless

Jak Charlton wrote re: Some comments are a total waste of time
on 09-30-2008 2:47 AM

I think Bob's comment was that this was a comment to be used by help generation programs, not to be read by the developer.

My view is that external APIs need documentation in this fashion, internal ones change too fast to be commented that easily, until the last few weeks approaching release.

Apart from those comments, almost universally, green stuff in my IDE is bad stuff - refactor to a better named method first

Dan Malcolm wrote re: Some comments are a total waste of time
on 09-30-2008 4:13 AM

I always pull this one out as an example:

writer.Formatting = Formatting.Indented; // set formating to be indented

writer.WriteStartDocument(); // document declaration

. . . . .

//remember to close the writer

writer.Close();

//flush out the response and close it

context.Response.Flush();

context.Response.Close();

Arjan`s World » LINKBLOG for September 20, 2008 wrote Arjan`s World &raquo; LINKBLOG for September 20, 2008
on 09-30-2008 10:12 AM

Pingback from  Arjan`s World    &raquo; LINKBLOG for September 20, 2008

Jak Charlton wrote re: Some comments are a total waste of time
on 09-30-2008 12:01 PM

@Dan - they closed it without warning the code would do that - how the hell is anyone gonna debug that

Daniel Pietraru wrote re: Some comments are a total waste of time
on 09-30-2008 12:28 PM

Short and to the point. Nicely done :)

I tried myself to investigate the other side of the comments story but I wasn't able to keep it that short:

littletutorials.com/.../how-bad-comments-are-born-in-your-code

PHenry wrote re: Some comments are a total waste of time
on 09-30-2008 1:23 PM

In my last job I had the architect actually rip through my code and one of the biggest comments was "I can't read your code, you don't enough comments, I don't read the code, I read the comments."  He was a very compitent Java developer but refused to read the code, prefering to scan the code and only look at the comments.  This frustrated me to no end as I use "self documenting code" style for my method and variable names but it was totally lost on him. :<

EricTN wrote re: Some comments are a total waste of time
on 09-30-2008 8:19 PM

I couldn't agree more.  Comments seem to either be missing completely, or are superfluous in so many instances.  First of all, the best documentation is well-chosen names (also something in sadly short supply).  But you're right - specify intent when intent isn't obvious.  And when the logic is tricky, the intent often isn't obvious.  I also agree with the idea of refactoring into smaller bite-size pieces, once again with well-chosen names.  The HACK comment used to confuse me too, until I saw it done by another programmer on a project I was recently on - he was using it  (HACK - BEGIN / HACK - END) to block out known temporary pieces of code that facilitated running logic through areas that would've otherwise be un-invoked because of unfinished outside dependencies.  Seemed reasonable to me.

Chipping the web: September 30th -- Chip’s Quips wrote Chipping the web: September 30th -- Chip&#8217;s Quips
on 10-01-2008 10:00 AM

Pingback from  Chipping the web: September 30th -- Chip&#8217;s Quips

Ollie Riches wrote re: Some comments are a total waste of time
on 10-02-2008 12:18 PM

'Some comments are a total waste of time'

IMHO 99% of all comments are a waste of time, anyone who uses a comment like that for documentation purposes is deluded into thinking that is of any use...

fsilber wrote re: Some comments are a total waste of time
on 10-03-2008 11:20 AM

The ability to recognize and write an appropriate code comment uses the same brain cells as that required to recognize or write the topic sentence of a paragraph.  Unless you attended some kind of elite school, chances are you remember plenty of kids who just couldn't absorb the concept.  Unfortunately, many programmers fall into that category (and would probably say, "I went into computer science because I hated my English courses.")

It's like a person who understands how a car works and can fix one, but who has no idea what you're getting at when you ask to explain how a car works by describing the major subsystems.  As far as he's concerned, it's just 5,000 individual parts connected together, such that this piece of metal presses on that piece of metal, which pulls on that piece of rubber which ....

About The CodeBetter.Com Blog Network
CodeBetter.Com FAQ

Our Mission

Advertisers should contact Brendan

Subscribe
Google Reader or Homepage

del.icio.us CodeBetter.com Latest Items
Add to My Yahoo!
Subscribe with Bloglines
Subscribe in NewsGator Online
Subscribe with myFeedster
Add to My AOL
Furl CodeBetter.com Latest Items
Subscribe in Rojo

Member Projects
DimeCasts.Net - Derik Whittaker

Friends of Devlicio.us
Red-Gate Tools For SQL and .NET

NDepend

SlickEdit
 
SmartInspect .NET Logging
NGEDIT: ViEmu and Codekana
LiteAccounting.Com
DevExpress
Fixx
NHibernate Profiler
Unfuddle
Balsamiq Mockups
Scrumy
JetBrains - ReSharper
Umbraco
NServiceBus
RavenDb
Web Sequence Diagrams
Ducksboard<-- NEW Friend!

 



Site Copyright © 2007 CodeBetter.Com
Content Copyright Individual Bloggers

 

Community Server (Commercial Edition)