On Fri, Oct 3, 2008 at 4:52 AM, Florent Becker <[EMAIL PROTECTED]> 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 _______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
