Re: About method comments

Yanni Chiu wrote:

Sigh. Why is it that most of those arguing for method comments
like to portray as lesser or lazy programmers, those that argue
against lots of comments.

I don't speak for the other pro-comment people, but in my case it is because
that is exactly what my experience has been.


Writing good documentation takes time. Method comments are not
a substitute for good documentation and specifications. If those
docs are required then account for it and get the right people
the write them. Writing prose, quickly and clearly, is not a
skill all developers necessarily possess. Wouldn't it be more
effective and efficient to have developers stick to coding -
spending their time refactoring, choosing good method and variable
names and writing test cases - rather than writing prose in comments.

There are two questions here (in part I'm responding to some of your points
from later in this thread). One is where the documentation should go, and the
other is who should write it and when.

Lets start with external documentation. I agree that not all (good)
programmers have the talent to write good extended prose. However (as I think
you've have already said yourself) they /do/ have to be good communicators.
Otherwise how is the author of the external documentation to know /what/ to
write ? (There are good reasons for wanting to make the programmer write at
least the first draft of the external documentation, but that has little to do
with the point here). To be a good communicator requires at least some ability
to see things from the POV of the person(s) with whom you are communicating.
Even if they are in a position to be able to ask you questions, it's unlikely
that you'll fully understand the questions (see the issues behind them clearly
enough to undstand /why/ the person asked it), unless you have and use that
ability.

So to be a programmer requires at least the /ability/ to write good code-level
comments, whether or not you think it's necessary (or optimal) to do so.

Now, I claim that in order for code to be useful, most methods should be
commented. I further claim that the best person to write those comments is the
person who wrote the methods. And still further I claim that the best /time/
to write the comments is as the method is written -- before, or at-the-same-as,
not after. (As an aside I'll mention that writing commentary after the fact is
a horrendous chore, and I hate it as much as anyone -- the same does /not/
apply to writing commentary /as/ I write the code.)

The last step is to make three observations:

One is that the person writing the code is very poorly placed to make decisions
about what will, or will not, be clear to whoever comes after. He or she is in
the middle of the code, knows everything about the system (the owning class and
related classes) of which it forms a part. He knows what the method is for.
Quite possibly he's coding-in-the-debugger, in which case he has even /more/
immediate context. All in all, almost anything he can say will seem redundant
to him. But /none/ of that information is necessarily available to the person
reading the code. As an extreme -- but perfectly realistic -- example (one
that crops up daily), the reader may have been searching the codebase for
examples of how something should be used. If the code that provides the
example doesn't have enough context to make sense of the example without having
to deconstruct the system of which it is part, then the value of the example is
significantly lost. May even become negative.

The second is that people are lazy, good programmers are /especially/ lazy. If
you don't want to write comments, then your judgement of how much use a comment
will be can get skewed. If you sometimes "allow" yourself to get away with no
comment, then that will almost certainly become a creeping habit. You may not
get to the point of hypnotising yourself into thinking that comments are never
necessary, but you will almost certainly end up consistently erring in the
direction of under- rather than over-commenting.

Those two reasons alone make me recommend commenting /every/ method. If you
can't think of something sensible to say, that's because you are too close to
the code. Step back and think about it from another point of view. There is
/always/ something that needs to be said (or rather, counter-examples are very,
very, rare and can be treated as exceptions).

The third point is something that Vassily has touched on: redundancy. Rather
than elaborate on that here, I'll give a link to an old post of mine on C.L.S.D
where I tell a little (true) story illustrating the value of redundant
commentary (though not a method comment as it happens). It's a long post, and
mostly irrelevant here, so (for anyone who bothers to follow the link at all)
skip down to where I start: "I dispute the unspoken assumption that redundancy
is bad.", and to the anecdote: "How I Once Nearly Destroyed the Firm I Worked
For."

http://groups.google.com/group/comp.lang.smalltalk.dolphin/browse_frm/thread/87089b491529b143/dd13e83028d81b26

So, after all that, while I agree that deciding how much commentary is called
for is indeed a matter of balancing costs, risks, and benefits, I /don't/
believe that there are many contexts (and certainly not the ones that this
thread is about) where a /correct/ analysis will lead to code-level commentary
being even sparse, let alone absent.

-- chris


.

Relevant Pages

  • Library Design, the script kiddies nightmare.
    ... good across the board of assembler programming. ... With languages that have the capacity, libraries of reusable code make ... comes at a cost that some of the older assembler programmers will not ... The virtue of writing code in this modular format is that you can use ...
    (alt.lang.asm)
  • Re: build faster
    ... Which is faster right now, locating testing and learning the library, writing your own, or just coding from scratch. ... In addition to writing reuseable code you should be writing expandable code that is backward compatible. ... Now I see a lot of work other programmers have done where there is no OO, there often are no functions, this is all embedded calls and includes in html. ... A competent programmer seldom starts from scratch and has libraries of code which can be used on almost any project ...
    (comp.lang.php)
  • Re: Static vs. Dynamic typing (big advantage or not)---WAS: c.programming: OOP and memory management
    ... I don't remember ever writing just three lines of code - even at ... Incompetent programmers and crap code - both of which exist - are just one ... > refactorings in static languages is more difficult than in dynamic ...
    (comp.object)
  • Re: Static vs. Dynamic typing (big advantage or not)---WAS: c.programming: OOP and memory management
    ... I don't remember ever writing just three lines of code - even at ... Incompetent programmers and crap code - both of which exist - are just one ... > refactorings in static languages is more difficult than in dynamic ...
    (comp.programming)
  • Re: Portability: Harmony between PC and microcontroller
    ... so programmers writing looks-like-C for them need to be ... I was hesitant to rely on rules from the Standard when it ... The problem comes with writing portable code. ...
    (comp.lang.c)