[webkit-dev] Comments in the code (Was Please include function-level comments in change log entries)

[Ryosuke Niwa]

On Wed, Jul 11, 2012 at 10:44 AM, Adam Klein <adamk at chromium.org> wrote:

> On Wed, Jul 11, 2012 at 9:51 AM, Ryosuke Niwa <rniwa at webkit.org> wrote:
>
>> On Wed, Jul 11, 2012 at 9:30 AM, Yaar Schnitman <yaar at chromium.org>
>>  wrote:
>>
>>> [(dev time of maintaining comments) + (risk of outdated comments causing
>>> bugs X dev time of fixing resulting bugs)] << (dev time gained by more
>>> contributors each being more knowledgable)
>>>
>>> No?
>>>
>>
>> How did you reach such a conclusion? Do you have any data points to
>> support that?
>>
>
> Not sure about data points, but anecdotally I've noticed it's common
> practice in WebKit to point newbies at particular contributors for
> explanations of how things work (e.g., "oh, selection? that's tricky, ask
> rniwa"). It seems plausible that some of the overhead of "oral tradition"
> could be reduced by judicious application of comments (as well as other
> written documentation, of course, like Dave Hyatt's blog posts and various
> wiki pages).
>

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.

Selection, for example, is a very complicated beast and even I don't fully
understand all the details even though I'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've been working
on this blog post about bidi text selection for the past 2-3 months and I'm
not even half way done yet.

On Wed, Jul 11, 2012 at 10:47 AM, Per Bothner <per.bothner at oracle.com>wrote:
>
> On 07/11/2012 09:51 AM, Ryosuke Niwa wrote:> On Wed, Jul 11, 2012 at 9:30
> AM, Yaar Schnitman <yaar at chromium.org
>
>> How did you reach such a conclusion? Do you have any data points to
>> support that?
>>
>
> It seems plausible.  I doubt we have any data points to support the
> opposite conclusion.


I don't think anybody had claimed the opposite conclusion.

Given that, I would suggest it is better for an
> open-source project to err on the side of more public information
> (i.e. openness) rather than less.


Let us not start name calling.

- Ryosuke
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120711/3ee602b7/attachment.html>