<div dir="ltr"><br><br><div class="gmail_quote">On Sat, Oct 4, 2008 at 5:45 AM, David Roundy <span dir="ltr">&lt;<a href="mailto:daveroundy@gmail.com">daveroundy@gmail.com</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<div class="Ih2E3d">On Fri, Oct 3, 2008 at 4:52 AM, Florent Becker<br>
&lt;<a href="mailto:florent.becker@ens-lyon.org">florent.becker@ens-lyon.org</a>&gt; wrote:<br>
&gt; Eric Kow &lt;kowey &lt;at&gt; <a href="http://darcs.net" target="_blank">darcs.net</a>&gt; writes:<br>
</div><div class="Ih2E3d">&gt; Sorry, in my precipitation i forgot to say that these patches reflect what I<br>
&gt; understand from the code, and that as for this module, I was not positively<br>
&gt; sure of everything. I was implicitly counting on your review, but better make<br>
&gt; it explicit.<br>
&gt;<br>
&gt; Is it ok with you if I send a first version of each patch where I tag strings<br>
&gt; I&#39;m not sure of, or questions I have? These would of course not be for<br>
&gt; application on <a href="http://darcs.net" target="_blank">darcs.net</a>, just for review and to start discussion. Then I would<br>
&gt; resend a definitive version. If you don&#39;t have time to answer, then I can just<br>
&gt; delete the unsure strings in the definitive version.<br>
<br>
</div>I&#39;ll welcome (and apply) haddock patches (or comment patches in<br>
general) that include personal statements of uncertainty. &nbsp;This adds<br>
transparency to the comments, and helps other developers to interpret<br>
them properly. &nbsp;Later patches can remove the uncertainty.<br>
<br>
e.g. a patch like<br>
<br>
--| invisiblePS doesn&#39;t seem to print anything, which seems a bit odd<br>
to me. &nbsp;- Florent<br>
<br>
would be welcome. &nbsp;It wouldn&#39;t add confusion, since noone would assume<br>
that that documentation is correct and misuse the function as a<br>
result. &nbsp;In general, I would encourage signing of comments like this<br>
when there is the least doubt, since my single greatest concern about<br>
haddocking everything is that it may cause bugs, and since any<br>
incorrect documentation can very easily cause bugs, if other<br>
developers assume that it is correct. &nbsp;But it&#39;s really hard to find<br>
bugs in documentation, particularly since the compiler and test suite<br>
can&#39;t help us.<br>
<br>
Which is why I&#39;m not a huge fan of comments--it&#39;s such a common source<br>
of bugs. &nbsp;It&#39;s better to write readable code, and better to read code,<br>
when trying to figure out what a function does. &nbsp;If the code is<br>
complicated, then it probably does something complicated, and odds are<br>
high that a simple explanation may lead to bugs.</blockquote><div><br>Maybe darcs devs should take a look at some of the advice here:<br>
<a href="http://c2.com/cgi/wiki?ToNeedComments">http://c2.com/cgi/wiki?ToNeedComments</a><br>
<a href="http://c2.com/cgi/wiki?TreatCommentsWithSuspicion">http://c2.com/cgi/wiki?TreatCommentsWithSuspicion</a><br>
<br>
That wiki as a whole has a lot of discussions about how to best do X
and Y, pragmatically.&nbsp; Some of it is excellent advice, but as always
don&#39;t trust everything you read.&nbsp; Question it and see how it fits with
your personal experiences or other sources.<br>
<br></div><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
I &nbsp;don&#39;t intend to discourage you from working on haddock (since much<br>
of darcs&#39; &nbsp;code is *not* well-written, and there are many cases that<br>
even well-written code is complicated and hard to read, but does<br>
something simple), but rather to &nbsp;encourage you to be cautious, and in<br>
particular, not to rely on your reviewers catching anything you may<br>
have written that was wrong.</blockquote><div><br>On a side note David, when I first read what you wrote I thought you
were saying essentially this: &quot;Comments are not perfect therefore we
should discourage them.&quot;&nbsp; I think what you&#39;re saying is instead that,
when our code can&#39;t be transparent comments are welcomed.&nbsp; Eg., the
priority is on well written code and only then on well written comments.<br><br>My working model of why/when to comment code (here, I&#39;m thinking of my day job for example), is that you don&#39;t comment what the code does, but *why* the code does it.&nbsp; 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.&nbsp; 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.&nbsp; Even if it&#39;s just to save myself X/2 minutes later.&nbsp; (I admit, todos and fixmes are better off in a bug database but they have a tendency to end up in comments also.)<br>
<br>Note that I say, &quot;you document assertions&quot;.&nbsp; This is because, there is more to commenting on the code than just language based comments.&nbsp; As the wiki links above point out, if you can turn a comment into code, do so!&nbsp; It&#39;s much better to throw in an &#39;error &quot;foo&quot;&#39; when the assumption foo is violated than it is to throw in a comment.&nbsp; Same goes for logging.&nbsp; Actually, for this reason, I think our &quot;impossible&quot; macro is flawed.&nbsp; Too few of our uses of impossible provide an intuition, defense or proof of why it is impossible.<br>
<br>Florent, please keep the API comments coming, haddock primarily fills that last point I mentioned for why to comment, and that&#39;s to explain an API.&nbsp; 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.<br>
<br>Thanks,<br>Jason<br></div></div><br></div>