[darcs-users] darcs patch: haddockification of Printer

Jason Dagit dagit at codersbase.com
Sat Oct 4 21:34:44 UTC 2008


On Sat, Oct 4, 2008 at 5:45 AM, David Roundy <daveroundy at gmail.com> wrote:

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


Maybe darcs devs should take a look at some of the advice here:
http://c2.com/cgi/wiki?ToNeedComments
http://c2.com/cgi/wiki?TreatCommentsWithSuspicion

That wiki as a whole has a lot of discussions about how to best do X and Y,
pragmatically.  Some of it is excellent advice, but as always don't trust
everything you read.  Question it and see how it fits with your personal
experiences or other sources.

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.


On a side note David, when I first read what you wrote I thought you were
saying essentially this: "Comments are not perfect therefore we should
discourage them."  I think what you're saying is instead that, when our code
can't be transparent comments are welcomed.  Eg., the priority is on well
written code and only then on well written comments.

My working model of why/when to comment code (here, I'm thinking of my day
job for example), is that you don't comment what the code does, but *why*
the code does it.  You document assertions, you provide references to
proofs, you explain intent, you insert mnemonic devices, poems about
correctness, links to email discussions, todo items, fixmes, api details,
etc.  Taking this one step further, I do personally feel that whenever
reading code takes me more than X minutes to figure out a few lines of code
that comments summarizing what I learned are relavent.  Even if it's just to
save myself X/2 minutes later.  (I admit, todos and fixmes are better off in
a bug database but they have a tendency to end up in comments also.)

Note that I say, "you document assertions".  This is because, there is more
to commenting on the code than just language based comments.  As the wiki
links above point out, if you can turn a comment into code, do so!  It's
much better to throw in an 'error "foo"' when the assumption foo is violated
than it is to throw in a comment.  Same goes for logging.  Actually, for
this reason, I think our "impossible" macro is flawed.  Too few of our uses
of impossible provide an intuition, defense or proof of why it is
impossible.

Florent, please keep the API comments coming, haddock primarily fills that
last point I mentioned for why to comment, and that's to explain an API.  I
look forward to a time when interfacing with most of the darcs code is as
simple as looking at the haddock to get a feel for what functionality is
available.

Thanks,
Jason
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.osuosl.org/pipermail/darcs-users/attachments/20081004/5cc30965/attachment.htm 


More information about the darcs-users mailing list