It is not just members, but also the implementation of interface methods, abstract methods, etc. This way you have a certain “color” for those “structural comments” in your head and your brain can skip that code much quicker when you are actually searching for something else. You dont have to read/understand it, because of the “structural comment” on top of it, you can just pretend that section isnt even there. But for that your brain has to have that color/comment-style stored so that it can skip it without actually telling you what it stands for. I agree that it is bullshit for imports/class definitions, but being able to quickly go through the segments of a class is very nice and a great way to save time if your class is between 400-800 lines, which unfortunately happens rather quick with Java .

@Sakuraba: I’m not sure if I can agree with that unless the class has a lot of members. And that by itself is a code smell, isn’t it?

@PhilLo: Good point, I didn’t think of the out-of-sync comment. And I have to confess, I did headers and useless comments too, mostly out of lacking experience. On the other hand it’s all about improving your skillsets, right?
The legacy part is definitely a sad truth, I’m having my fair share of legacy code…

@Nicolas: You’ll have to understand the situation that I was in when I wrote this post. Me and my team spent several days of crunch time digging through legacy and newly developed code. I was not amused that the quality of the new code was really really bad. The team that wrote it spent probably more time making their code comments look pretty than actually improving the object design of their code. I guess it was also me venting after several long and frustrating work days.
With that out of the way, I disagree on the point [1] that arguments against self explanatory comments (that is what I believe you meant, you wrote “code”). Yes, it is kind of pointless to argue about something that is obviously bad, however I tried to make a point about which types of code comments I consider bad or at least non-beneficial. Also, when I went to university, we were told that every element had to be documented which leads to comments documenting the obvious. If only a few grads read this and start questioning what they get taught, I’m happy.
Regarding [2.], yes, I am too young to remember day’s without SCM. But this is 2011 and SCM are cheap and effective. So when I find large portions of commented out code in newly developed code, I really have to wonder.
Regarding [3.], you kind of have a point there. However, it’s part of an argument that leads to my final point, “Final Advice”, where I try to explain how to avoid useless comments or write better code.

I guess my post is poorly titled, I’m don’t believe code comments are useless. In fact, comments (and here I really think javadoc style comments) are an essential tool to document and explain an API. Every package should have a high level description of its intention and usage. But most comments I encounter at work are useless, obvious and pointless comments of the above categories.

If time permits, I’m planing to write a post about how to write good comments, so I’m really thankful for every piece of criticism, both positive and negative.

@Sam:
I agree, and in fact, 49% of all developers are sub-standard. And to be honest, I don’t consider myself a top developer either, which means I usually stumble about things like bad code comments. On a high or conceptual level comments/documentation are essential, I second that.

@Anders:
Good point, I haven’t thought about that. You have a point there; I think it comes down to my argument about “documenting the obvious”. If a getter gets documented, it should be more specific than just “returns x”.

You assume that most people are ‘good programmers’. I’ve seen things that certainly classify as good comments – there are a variety of valid reason why you should write comments!
(e.g. the functional spec is probably not going to be available to the unfortunate person who needs to fix a bug in the code at mid-night. Explaining why a the code is supposed to throw a particular exception (even though the function spec/Tech spec) clearly specifies it might not be so bad.

I upgraded my opinion of using ‘loggers’ and code technique when possible over comments some months!

Personally I think that stuff is usually under documented rather than over documented.

Well, I would like to raise some points:

1. Arguments against self-explanatory code are not valid. This is a low-level as can be. Please, isn’t it evident that this is bad? Do you really need an article to tell us?
2. The famous commented out code. Perhaps you’re too young to remember but there was a time when most projects didn’t use a VCS. Why? Because they were expensive (like IDEs were but this a story for antoher time). The only thing that saved those projects was commenting out code. Now, some people still do it. It’s bad but has nothing to do with comments.
3. Irrelevant comments are also bad. My gosh, is it true? I didn’t know that before.

Again, not to go against the majority of yes-man, but comments are necessary. Why? Because when you work in real life projects, there’s a thing called maintenance. And you do maintenance much more often than true development. In this case, you’re a lot happier to read 10 comments lines that 10 Java files code. How do I know? Because I was the man who had to update features on your crappy code and had to read uncommented Java files.

Trying to dry your cat in the microwave oven doesn’t make an argument against using the same oven to eat your food.

The only thing left is that comments should explain what, not how (and in any case not paraphrase the code).

So, please stop the comments bashing thread and write something that can really make things go forward.