Steve Eichert

My Opinion?

I find the whiners who cry foul about too many comments lazy people who shouldn't call themselves 'developer'.

Comments are part of the sourcecode. Not for the compiler, but for the HUMAN reader of the sourcecode. Humans are very bad in interpreting computer language, comments (they have to be correct) HELP the human understand the program code he's reading.

_THAT_'s why comments are ESSENTIAL. Everyone who is denying that should step away from the keyboard and move over to McDonalds to flip some burgers.

Yes I'm a little annoyed by this dog-old discussion. It gets out of proportion. You anti-comment people should realize who reads your blogs: novice programmers and other starters. Are they helped with advice of 'less comments are good'? No, not a single second.

Oh, and before someone tries to tell me I don't get it with lame arguments as "but they are never correct" and "I prefer no comments over bad comments": comments are part of your sourcecode, they should describe what the code does, SEMANTICALLY, so the reader (human!) has less problems understanding what it does. Because comments are part of the sourcecode, they have to be kept up to date.

Yes, that's tedious, so is developing a HELPFULL gui and great documentation. I comment a lot, over 30% of my sourcecode is comment. It proves time and time again it's well worth the effort, even though my code is pretty clear: you can't describe all semantics in a method name or parameter name. Comments make the difference between hard to understand complex code and easy to understand complex code.

But it's of course up to you, I don't have to work with your code. :)

Comments are necessary, and should be used whenever possible. Without commenting, it would be a royal pain in the arse to step through other people's code, when you're tasked with making a change two years down the road. I know because I've done this many a time at the workplace, where the original coders left little documentation behind, which makes my job a lot more difficult than it should be.

And one more thing, Real Programmers...

<a target="_new" href="http://www.melloblog.com/Feedback.aspx?BlogID=60">http://www.melloblog.com/Feedback.aspx?BlogID=60</a>

I'm definitly pro-comments.

And about the &quot;I prefer no comments over bad comments&quot;. I come across comments like the next one all the time!

// Begin loop
while ( ...

There's another thing to the &quot;no comments over bad comments&quot;, because the type of comments I just mentioned irritate the @)#$*#^&amp; out of me and I start throwing with keyboards, books and sometimes even monitors when I see something like that.
As if I don't understand we're going into a loop of some kind. You (#&amp;$(# moron!

Please people, describe what the loop is for!!! Or any other code, for that matter.

I just finished another project where I had to add some functionality to an existing WinForms application. The application was really simple, however badly written. But some business rules and calculations and stuff, were pretty hard an there were a lot of them! And ofcourse, no documentation and no comments. &quot;We prefer extreme programming here, so we don't have any docs and/or comments&quot;. Yeah, sure! That's wat XP is all about.

Anyway, because of the time, I wasn't allowed to write any docs. But I definitly took my time to write A LOT of comments, if any other developer might ever come by and has to add even more functionality.

Some people really don't get it, but you still have to (learn to) work with them! :)

Frans, What do you call the whiners who cry foul over too few comments? :-) It was there for the taking and I couldn't resist!

Anyway, on to the arguments.
#1) Agreed, comments are for the human reader, they should be used to shed light on code that is difficult to understand.
#2) Although flipping burgers sounds appealing I think I'll stick with what I'm doing now...at least for the time being. Cause...hey...who would be hear to take your insults if I went and did that?
#3) I hope those just getting started do read arguments that say you shouldn't comment, in fact, I think they should try and read as many different opinions on every aspect of software development that they can. I hope they think about what they're commenting and why. I'll stand by the statement, when you think you need a comment think about how you can improve the readability of your code. Often times refactoring your code can make its intent clear. You may still want a comment, but, by looking at your comment as a warning you've made the code clearer. Do you agree this is a good thing?

In summary:

Should we code without any comments? Probably not.

Should we throw a comment on every line of our code? No.

Should we treat the need for a comment as a warning? Yes.

Should we listen to the arguments made by the whiners who say we don't need comments? Yes.

Should we listen to the arguments made by the whiners who say we do need comments? Yes.

Should we stop calling each other whiners? Yes.

Should we code by intent to make the need for lots of comments unnecessary? Yes.

Should I stop with all the Should we's? Yes.

Michael, Real programmers do code in BINARY!

Steve, this discussion is so old and stupid, it hurts. It falls in the same category as discussions about the length of a method (&quot;must fit on a screen!&quot;), method names, parameter names, prefixing of private member vars, VB.NET vs C# vs C++ vs Java, AMD vs Intel, NVidia vs ATi etc. etc. etc.

I really don't care if you don't include comments in your code, it's your code, you have to deal with the consequences. (If you're lucky, someone else has to). What I do care about is the preaching tone coming from a couple of people who want to tell the world that comments in code are not that useful and what have you. These people don't understand who reads their blogs. There are people out there who didn't have a degree in Computer science, who develop software for a year or so, maybe less. These people read your blogs too.

I think you and your fellow anti-comment friends should think twice before you put up 'suggestions' like you have done.

How long do you write software as a professional, Steve? How often is it that you have to change/work with older code, a year, 2 years old maybe, yours or OTHER people's code? I have the feeling you haven't did that a lot. Because if you had, you would have known that comments are essential in understanding code. You think you can solve that by making cleaner code? My code is already very very clean, I can tell you that, but still requires comments, and I'm very happy they're there so I can jump right in when altering some code in the 3MB (!) big codebase I'm still working on.

&quot;Often times refactoring your code can make its intent clear. You may still want a comment, but, by looking at your comment as a warning you've made the code clearer. Do you agree this is a good thing?&quot;
This is a bogus statement. Refactoring doesn't help you in a lot of occasions. Fire an event, or worse: do something which fires an event, or set some properties and call a method. What will happen? You THINK you are able to predict that? I can assure you you can't, because you're human. You don't have a locals stack in your head and no C# interpreter. You don't know where execution continues after setting myControl.Checked = true; or ((IEntity)value).SetupSync(this); or WHY you have 2 code paths in ITypedList.GetItemProperties().

&quot;Should we code without any comments? Probably not.&quot;
Like I said, you should do what you have to do, however your code is incomplete without comments and will bring a BIG BAD Burden on the shoulders of anyone who has to work with YOUR code.

&quot;Should we throw a comment on every line of our code? No.&quot;
THis is a typical statement from a person who thinks comments are somewhat or completely useless. Who thinks I comment on every line? Who says you have to do so? Which part of &quot;Describing the code's semantics&quot; do you not understand, Steve?

&quot;Should we treat the need for a comment as a warning? Yes.&quot;
NO!
I can give you a lot of examples which CAN'T be refactored but need comments right there in the code. It's completely arrogant to think your code is understandable by everyone, because it isn't. You will have a hard time working with your own code when you look at it again a year from now.

&quot;Should we listen to the arguments made by the whiners who say we don't need comments? Yes.&quot;
NO! Please, think twice about who reads your blogs, you are NOT doing novice programmers a favor!

&quot;Should we listen to the arguments made by the whiners who say we do need comments? Yes.&quot;
If you think I'm a whiner, Steve, so be it. But I can tell you, I know a hell of a lot about writing and designing software. If you think I 'whine' because I have something to say about this, feel free to ignore me, but don't be surprised when you have to conclude some day &quot;He's right&quot;.

&quot;Should we stop calling each other whiners? Yes.&quot;
I find these &quot;Comments are bad&quot; discussions becoming pretty annoying, actually. I didn't expect you on the anti-side actually. Often you see developers who think they're smart but are really not that talented on the side of the anti-comment crowd. The same people who also think you don't need documentation, because code documents itself. Yeah right!!!

&quot;Should we code by intent to make the need for lots of comments unnecessary? Yes.&quot;
Again a statement you often see from the anti-comment people. What's wrong with a comment in the code? It seems it will bite you or something. Comments who describe semantics of the code are good and should be there and STAY there. They're part of the code, as the XML comments are on EVERY method (also private methods!!). This is so incredible arrogant, you won't believe it. &quot;When you feel the urge to put a comment, your code is probably bad&quot;. People who think that kind of statements are valid SHOULD stop producing software, because they will cause problems for themselves later on, their employers and collegues.

Steve, again, I didn't expect an anti-comment statement from you. I'd suggest to take a step back and re-consider your statement. I *know* for a fact that comments help, work and should be used CORRECTLY and kept in sync with the code. People should be taught to do THAT instead of removing the comments and tell themselves the code is clear, while it CAN'T be clear enough because a human doesn't understand C# error-free.

To help you with reconsidering your statement, Steve, look at 'polymorphism'. You have a given instance in a piece of code, you call a method, which method will be called, what will it do? Often patterns are implemented accross a couple of classes/methods. It is easy to completely lose overview when you're reading the code, no matter how much time you put into setting up the code and how many times you refactor the cr*p out of it.

A couple of well formulated comments in the code can help the reader tremendously.

When I find that I have to dedicate considerable effort to explaining my code in my comments, I usually take a moment to reflect if my code could be more clear.

This doesn't mean I want to do away with comments. Rather, by commenting my code, I can often detect that code that I thought was clear enough perhaps, on reflection, isn't.

That is, large and ugly comments are probably &amp;quot;smells&amp;quot; of ugly code. When the comments can be clean and nice, then so is probably your code.

If the code and the comments become clean enough, of course there's going to be the temptation to do away with the comments (I don't have any strange code to explain anymore) but I'll have to agree with Frans that this temptation should be resisted.

/Mats Helander

Frans, Whether or not you realize it we do agree on a lot of what's being discussed here. You've assumed I don't think comments should be written at all. This isn't the case. I never said don't ever write comments. What I did say is that you should make your code as clear as possible before writing comments. We obviously disagree here, which is fine.

It's somewhat ironic that you took offense to the whiner statement since the only reason I wrote that was because you made the statement. In order to make sure there isn't any confusion, I don't think your a whiner.

Take Outs for 16 May 2004

Very interesting discussion! A couple of things:

On XML comments: XML comments are there to document the public interface of a class, not its internal workings. They're written for a different audience than in-line comments; keeping that distinction in minds helps.

On commenting semantics: I agree with Franz's point about the need to comment complex semantics. A comment around a complex conditional can do wonders. However, I prefer to put more of my thought into (a) naming my methods accurately and (b) using good procedural abstraction. Keep methods short, simple, and accurately named and the semantics will largely become self-evident.

Finally, I'm surprised that nobody's brought up the role that unit tests play in communicating how a codebase works. If there is a suite of precise unit tests that exercise portions of the code independently, then those unit tests become the gateway into understanding the code. Unit test code that can be stepped through in the debugger is better than even the most eloquent comments, IMHO.

Steve, I agree regarding the Xml comments although my post mistakenly doesn't indicate that. I also agree on Frans point regarding complex semantics. A good comment on a complex set of code can definitely make all the difference.

For some reason the unit tests never came to mind. They can definitely help indicate how and when different classes are used within an application. With the help of TestDox (NTestDox) we can even generate a little documentation from the unit tests.

it's annoying when people go &quot;OMG I CAN'T READ YOUR CODE CUZ YOU DIDN'T USE COMMENTS.&quot; Good programmers should be able to read code and know what the programmer is trying to do.