A comment on the comment on comments (97 things)

[Martin Larsson]

Hi Kevlin.
And the rest.

Reading the book, I found Cal Evans' contribution (#16, A comment on comments) and your first (#17, Comment Only What the Code Cannot Say) to be rather conflicting.
My take on comments is:

You don't need comments

If you need a comment, you can write the code better

If you still need a comment, it should focus on 'why' since the code takes care of 'what' and 'how'

This seems more in line with your contribution, while Cal Evans' has, among other things:

Inside your code should be explanations about what the code is supposed to be doing.

(97 things)

This makes me wonder why this contribution was included. Or am I misunderstanding something?

M.

[Raja Pal]

Dear Martin,

I wish to go with Kevlin's point of view - Comments are necessary and are not Evil! However usage of comments must be "sensible - where you ought or you did rather NOT" and "sensitive - you write comments for another human being - not a compiler"
#1. Comments become evil because of 3 types of developers viz.
a) negligent developers failing to update
b) lazy developers uncapable or unwilling to type sensible language
c) enthusiastic essayists who overdo their language skills and show it in code

#2. Comments are necessary not only to say "Why" but also sometimes "What". I agree they shouldn't have to say "how", because your code must speak for itself, XP. However let me share that in the last decade I have saved over a month of explanations because I commented what my code did and why it did stuff in a certain way, especially in situations where my code was:
a) Optimized
b) Compact - text and runtime size
c) Component based and needed a thrid party component(not always documented)
d) targetted to a scripted platform

#3. I still will like to say that your point here is very valid - "Never write a comment, till your code cannot be more expressive, so as to make the comment-superfluous!" except those odd situations where people choose platforms and environments where not all developers and component writers use clean Java code or open APIs.

[Kevlin Henney]

Yes, they are at certain points contradictory. In putting this book together I wanted to ensure that, where it benefited the reader, more than a single point of view was present in the text. I present appropriate diversity of considered opinion to demonstrate that some topics have a range, that you can learn a great by observing, considering and reasoning through differences.

As I said in the Preface to the book:

The contributions do not dovetail like modular parts, and there is no intent that they should--if anything, the opposite is true. The value of each contribution comes from its distinctiveness. The value of the collection lies in how the contributions complement, confirm, and even contradict one another.

I hope that makes the reason both were included somewhat clearer. As to the specific perspective I personally hold on this topic... well, I think you can guess!