I&#39;m gonna chime in here, as I am 3 months into working on WebKit and the lack of comments has driven me absolutely crazy.   This is a bit of a rant from a self-declared newbie, but I&#39;m trying to be constructive. I&#39;ve contributed to a handful of open and closed source projects. I am trying to help, so bear with me. Maybe I&#39;ll feel differently in a year, but this is how I feel today.<br>

<br>I&#39;ve mostly been hacking on IndexedDB but also poking around other areas just to try to learn how everything works. But as impressed as I have been with the quality of the code itself in WebKit, the lack of comments have made the learning curve very steep relative to anything else I&#39;ve worked on and frankly its nearly impossible to evaluate the quality of the architecture because of the lack of comments. It&#39;s been like doing research in a library where none of the books have tables of contents, indexes, or bibliographies except for stacks of form-feed paper in some back room (i.e. ChangeLogs). Sure, you can read each book page by page, but do you really want to? ack/grep only gets you so far.<br>

<br>Ryosuke, you said earlier: <br><br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"> To be fair, as I said, I was able to read WebKit code without much trouble 2-3 months into my internship. I&#39;m not sympathetic to people who can&#39;t read code as well as an undergraduate college student.<br>

 </blockquote><br><br>This has been my experience as well, and in my mind this is not something to be proud of. The learning curve on WebKit has been worse than probably any other project I&#39;ve worked on (and again it&#39;s not because the code is in any way poor!) At some level I could say that it&#39;s made me interact with other developers more in person/email/irc, but honestly that justification feels like a cop-out. The only place I&#39;ve seen this culture proliferate to such a degree is in the RoR community, and .. well.. <br>

<br>I&#39;ve wasted way more time groveling through the same code over and over, or bugging people when they have better things to do, trying to unpack why we return early in this case but not in that other case, or how on earth an object could end up in some particular state.<br>

<br>I absolutely do not buy that the &quot;cost&quot; of keeping comments up to date and the &quot;cost&quot; of out-of-date comments outweighs the benefits - that has NEVER been my experience and if anything the benefits of comments grow as the number of people on a project grows. 20 minutes of your time documenting/updating comments is worth 10 minutes of 10 (or 100) developers&#39; time *not* groveling through code. I also do not buy that all code can be written in a self-documenting fashion. That&#39;s like saying that nobody needs to write books about anything spec&#39;ed by the W3C. Code is not documentation no more than a spec is code.<br>

<br>If anything I&#39;m a firm believer that taking the time to write a comment forces you to write code correctly the first time. i.e. if I have to write in a comment &quot;this is true except in this one esoteric case&quot; then it forces me to reexamine that esoteric case and ask myself if that exception is really necessary. In fact the way I generally write my code in WebKit is to comment heavily so I can keep track of my own intentions, and then just before sending off for review, strip all my code of comments, and that&#39;s truly a waste.<br>

<br>I&#39;m not saying that comments can&#39;t get stale but I implore everyone to ask yourself: Have you actually encountered projects where a proliferation of stale comments has a noticeably bad effect on productivity? Was there any effort within the project community to improve the culture of keeping comments up to date? Were significant regressions added due to stale comments? How often did you encounter stale comments vs real, useful comments?Alec<div class="gmail_quote">

<br></div><div class="gmail_quote"><br></div><div class="gmail_quote">On Wed, Jul 11, 2012 at 10:58 AM, Ryosuke Niwa <span dir="ltr">&lt;<a href="mailto:rniwa@webkit.org" target="_blank">rniwa@webkit.org</a>&gt;</span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="gmail_quote">On Wed, Jul 11, 2012 at 10:44 AM, Adam Klein <span dir="ltr">&lt;<a href="mailto:adamk@chromium.org" target="_blank">adamk@chromium.org</a>&gt;</span> wrote:<br>

<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">

<div><div>On Wed, Jul 11, 2012 at 9:51 AM, Ryosuke Niwa <span dir="ltr">&lt;<a href="mailto:rniwa@webkit.org" target="_blank">rniwa@webkit.org</a>&gt;</span> wrote:<br></div></div><div class="gmail_extra">

<div class="gmail_quote"><div><div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div class="gmail_quote">



<div>On Wed, Jul 11, 2012 at 9:30 AM, Yaar Schnitman <span dir="ltr">&lt;<a href="mailto:yaar@chromium.org" target="_blank">yaar@chromium.org</a>&gt;</span> wrote:<div class="im"><br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">



[(dev time of maintaining comments) + (risk of outdated comments causing bugs X dev time of fixing resulting bugs)] &lt;&lt; (dev time gained by more contributors each being more knowledgable)<div><br></div><div>No?</div>



</blockquote><div><br></div></div></div><div class="im"><div>How did you reach such a conclusion? Do you have any data points to support that?</div></div></div></blockquote><div><br></div></div></div><div class="im"><div>

Not sure about data points, but anecdotally I&#39;ve noticed it&#39;s common practice in WebKit to point newbies at particular contributors for explanations of how things work (e.g., &quot;oh, selection? that&#39;s tricky, ask rniwa&quot;). It seems plausible that some of the overhead of &quot;oral tradition&quot; could be reduced by judicious application of comments (as well as other written documentation, of course, like Dave Hyatt&#39;s blog posts and various wiki pages).</div>



</div></div></div></blockquote><div><br></div><div>As discussed on IRC, we can do that more appropriately on blog posts, technical articles, and wiki pages where we talk about the overall picture on how things fit/work together.</div>



<div><br></div><div>Selection, for example, is a very complicated beast and even I don&#39;t fully understand all the details even though I&#39;ve been almost exclusively working on editing and have touched the selection code on numerous occasions. To understand how selection works, one needs to understand several classes like FrameSelection, VisibleSelection, Position, VisiblePosition, and Range on top of a large amount of rendering code. For example, I&#39;ve been working on this blog post about bidi text selection for the past 2-3 months and I&#39;m not even half way done yet.</div>



<div><br></div></div><div class="gmail_quote"><div class="im">On Wed, Jul 11, 2012 at 10:47 AM, Per Bothner <span dir="ltr">&lt;<a href="mailto:per.bothner@oracle.com" target="_blank">per.bothner@oracle.com</a>&gt;</span> wrote:<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">




On 07/11/2012 09:51 AM, Ryosuke Niwa wrote:&gt; On Wed, Jul 11, 2012 at 9:30 AM, Yaar Schnitman &lt;<a href="mailto:yaar@chromium.org" target="_blank">yaar@chromium.org</a><div>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
How did you reach such a conclusion? Do you have any data points to<br>
support that?<br>
</blockquote>
<br></div>
It seems plausible.  I doubt we have any data points to support the<br>
opposite conclusion.</blockquote><div><br></div></div><div>I don&#39;t think anybody had claimed the opposite conclusion.</div><div class="im"><div><br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">



Given that, I would suggest it is better for an<br>
open-source project to err on the side of more public information<br>
(i.e. openness) rather than less.</blockquote><div><br></div></div><div>Let us not start name calling.</div><span class="HOEnZb"><font color="#888888"><div><br></div><div>- Ryosuke</div><div><br></div></font></span></div>


<br>_______________________________________________<br>
webkit-dev mailing list<br>
<a href="mailto:webkit-dev@lists.webkit.org">webkit-dev@lists.webkit.org</a><br>
<a href="http://lists.webkit.org/mailman/listinfo/webkit-dev" target="_blank">http://lists.webkit.org/mailman/listinfo/webkit-dev</a><br>
<br></blockquote></div><br>