Derik Whittaker

just like twittering: "twittering"

=o)

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.

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

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.

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

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

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();

Pingback from  Arjan`s World    » LINKBLOG for September 20, 2008

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

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

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. :<

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.

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

'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...

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 ....