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

[Martin Geisler]

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.

> 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?

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?

-- 
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/20090926/b6b223ae/attachment.pgp