On Sat, Oct 4, 2008 at 5:45 AM, David Roundy <[EMAIL PROTECTED]> wrote:
> 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. 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
_______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
