[PATCH] dirstate: add/improve method docstrings and some comments

Adrian Buehlmann adrian at cadifra.com
Sat Sep 26 06:04:41 CDT 2009


On 26.09.2009 11:31, Martin Geisler wrote:
> Adrian Buehlmann <adrian at cadifra.com> writes:
> 
>> [...]
>>
>> Ugh. Does that help?
> 
> It helped me and I think such commentary really belongs in the source
> code -- right where it's needed by people like Greg.

My full cliff notes or Greg's shorter but not quite correct comment?

And my comment may contain bugs as well.

And I'm not even sure we would have that code bit in there
if Alexis would have been required to provide such a comment
when he committed that bugfix.

>> Anyway, it's pointless to try to describe the code with comments in
>> that level of detail.
>>
>> The source code *is* the ultimate precise formal description of the
>> program. Too much comment is just a call for confusion and disaster,
>> as no one dares to update it or correct it if the code is modified in
>> the future.
> 
> Why should people be afraid of updating a well-written comment? I can
> see a problem if the comments and code get out of lock-step, but is that
> not something we can promise each other not to let happen?

The old comment debate.

Comment should not describe in other words what the program does.
And that's exactly what I did (or tried to do).

See also the nice chapter "Bad Smells in Code", sub-chapter "Comments", in
the book "Refactoring" by Martin Fowler (1999), where he writes on page 87:
"...comments often are used as a deodorant. It's surprising how
often you look at thickly commented code and notice that the comments
are there because the code is bad."

I don't say the code is bad here, but it is a tricky edge, with
all these state changes, cached data and time dependent behavior.
Yes, you will say that's exactly an argument for more comment, but
I find it really hard to come up with a good short but still correct
description for what is happening there.

And if you abstract too far from the code, the comment becomes meaningless,
because it lacks precision.

And who wants to trust the comment? Who tests the comment?
If you need my comment to understand the code, then something
dangerous is happening. You start to rely on my comment instead
of interpreting yourself what the program is doing.

> It would be something for crew members to verify when reviewing patches:
> 
> * if they change a function with a docstring, do they update it?
> 
> * do they add a docstring for sufficiently complicated new functions?



More information about the Mercurial-devel mailing list