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

Yaar Schnitman yaar at chromium.org
Wed Jul 11 09:30:48 PDT 2012


[(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?



On Wed, Jul 11, 2012 at 8:53 AM, Ryosuke Niwa <rniwa at webkit.org> wrote:

>
> On Jul 11, 2012 8:43 AM, "John Mellor" <johnme at chromium.org> wrote:
> >
> > On Wed, Jul 11, 2012 at 4:21 PM, Ryosuke Niwa <rniwa at webkit.org> wrote:
> >>
> >> On Wed, Jul 11, 2012 at 6:54 AM, John Mellor <johnme at chromium.org>
> wrote:
> >>>
> >>> Even obvious (to some) concepts like InlineBox have subtleties, for
> example not all inline-level elements have inline boxes. An unambiguous
> class-level comment could make this clearer, for example:
> >>>
> >>> // An inline box represents a rectangle that occurs on a line,
> corresponding to
> >>> // all or part of some RenderObject. It must be inline-level and its
> contents
> >>> // must participate in its containing inline formatting context. For
> example a
> >>> // non-replaced element with a 'display' value of 'inline' generates
> an inline
> >>> // box, as does an anonymous inline element (text directly contained
> inside a
> >>> // block container element, not inside an inline element). But atomic
> >>> // inline-level boxes (such as replaced inline-level elements,
> inline-block
> >>> // elements, inline-table elements, and ruby elements) are not inline
> boxes
> >>> // since they participate in their inline formatting context as a
> single
> >>> // opaque box; these are handled by <insert class that deals with
> these>.
> >>> //
> http://www.w3.org/TR/2011/REC-CSS2-20110607/visuren.html#inline-boxes
> >>
> >>
> >> What's the point of adding this comment when the URL contains all the
> information?  All we need is the URL.  If anything, we should be describing
> the difference between the inline boxes in CSS2.1 and our implementation
> instead.
> >
> >
> > That would be great! I agree that there's probably limited value in just
> copy/pasting from specs like I did. Linking to the spec something is based
> on and describing the differences would add a lot of value.
>
> The problem is that we'll then incur the maintenace cost of keeping
> comments up-to-date and the risk of them getting out-of-date as we have
> previously discussed.
>
> - Ryosuke
>
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo/webkit-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120711/2b49baaf/attachment.html>


More information about the webkit-dev mailing list