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

[Martin Geisler]

Adrian Buehlmann <adrian at cadifra.com> writes:

> 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."

Heh, funny, I've never tought of them like that :-) But I can what is
meant by that comment...

However, I think that many newcomers are disappointed/surpriced by the
lack of comments in Mercurial's code. I remember I was at first. But
after reading some of the code I realized (as Greg says) that it is
amazing how few comments are needed in clear code. So I'm now okay with
the level of comments in the Mercurial code I look at.

-- 
Martin Geisler

VIFF (Virtual Ideal Functionality Framework) brings easy and efficient
SMPC (Secure Multiparty Computation) to Python. See: http://viff.dk/.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 196 bytes
Desc: not available
Url : http://selenic.com/pipermail/mercurial-devel/attachments/20090927/e39d13e9/attachment.pgp