My email is: iisrael13@yahoo.com

Thank you!

PMSL!!!!

lol. Where I’m from we refer to that as a “stove-pipe” system. That or a “duct-taped piece-of-sh*t”.

Eric: If a client REQUIRES comments (some do) then I tell them that I won’t add them until AFTER they agree on the software and check off that it is exactly what they want per the scope of the project. That way I don’t have to maintain / update comments. In that respect Eric, YOU hit the nail right on the head!

Personally I think the following method is commented enough just by naming conventions and constraints alone.

public static T CalculateMax(T first, T second) where T : IComparable
{
return second.CompareTo(first) < 0 ? first : second;
}

And what happens to your comment when someone changes the color scheme?

“No matter how you look at it, code is still a “code”… and is no replacement for natural language.”

I look at it the exact opposite way. I can actually read code and understand what it’s doing. People have a very difficult time understand things. I’d rather see this:

if(element.isSelected()) {
highlight(element);
}

Than:

// Draw a red box around the selected element.
[imaginary code to find the selected element and position the drawing cursor near it]
this.lineStyle(1, 0xFF0000, 100);
this.moveTo(100, 100);
this.lineTo(200, 100);
this.lineTo(200, 200);
this.lineTo(100, 200);
this.lineTo(100, 100);

I generally read comments as an excuse for not being able to do something correctly. I certainly *write* them that way. Browsing through my code you’ll find a lot of what appears to me to be obvious (with documentation comments on public interfaces). The non-documentation comments describe why I couldn’t make something obvious for whatever reason (broken APIs, performance problems, etc…)

I’ve read many misleading comments in my time, and I’d really just rather not have some English lying to me about code I can already see.

Will, you hit the nail on the head. Comments are never an acceptable substitute for well-written readable code. I would even go the extra mile to write less efficient / easily comprehensible / easily maintainable code than to have an extremely code-efficient piece of code that nobody can understand.

The most useful commenting that anyone can do is to choose your method names and member names descriptively and carefully.

Comments are useful to explain non-obvious techniques, and to give a short, general purpose statement for a piece of code — the fewer the comments required the better.

The inherent problem with comments is that they can never be tested. Code can be tested, but comments cannot. Once comments are created, they must be maintained along with the code (adding to the burden of software maintenance), or else they will become a liability to the code. I have inherited code from other developers that did not match the code! I don’t know if it was just commented incorrectly to begin with, or if the “comment rot” was contributed by people not maintaining the comments after software changes were made.

I agree with the basic approach that you should always succinctly comment your intent. In my experience, I find that if a developer can’t “touch-type” they’re less likely to comment their work.

Also, on one project I did I received very positive feedback from a happy client that was something to the effect of “I don’t know C#, but I could understand what was going on.”

Commenting now is all about future productivity.