[darcs-users] darcs patch: haddockification of Printer

[David Roundy]

On Fri, Oct 3, 2008 at 4:52 AM, Florent Becker
<florent.becker at ens-lyon.org> wrote:
> Eric Kow <kowey <at> darcs.net> writes:
> Sorry, in my precipitation i forgot to say that these patches reflect what I
> understand from the code, and that as for this module, I was not positively
> sure of everything. I was implicitly counting on your review, but better make
> it explicit.
>
> Is it ok with you if I send a first version of each patch where I tag strings
> I'm not sure of, or questions I have? These would of course not be for
> application on darcs.net, just for review and to start discussion. Then I would
> resend a definitive version. If you don't have time to answer, then I can just
> delete the unsure strings in the definitive version.

I'll welcome (and apply) haddock patches (or comment patches in
general) that include personal statements of uncertainty.  This adds
transparency to the comments, and helps other developers to interpret
them properly.  Later patches can remove the uncertainty.

e.g. a patch like

--| invisiblePS doesn't seem to print anything, which seems a bit odd
to me.  - Florent

would be welcome.  It wouldn't add confusion, since noone would assume
that that documentation is correct and misuse the function as a
result.  In general, I would encourage signing of comments like this
when there is the least doubt, since my single greatest concern about
haddocking everything is that it may cause bugs, and since any
incorrect documentation can very easily cause bugs, if other
developers assume that it is correct.  But it's really hard to find
bugs in documentation, particularly since the compiler and test suite
can't help us.

Which is why I'm not a huge fan of comments--it's such a common source
of bugs.  It's better to write readable code, and better to read code,
when trying to figure out what a function does.  If the code is
complicated, then it probably does something complicated, and odds are
high that a simple explanation may lead to bugs.

I  don't intend to discourage you from working on haddock (since much
of darcs'  code is *not* well-written, and there are many cases that
even well-written code is complicated and hard to read, but does
something simple), but rather to  encourage you to be cautious, and in
particular, not to rely on your reviewers catching anything you may
have written that was wrong.

David