[webkit-dev] coding style and comments
eric at webkit.org
Thu Jan 27 15:46:11 PST 2011
My personal preference (and I'd love to hear from other contributors)
is that code should ideally be self-documenting.
If I ever find myself writing a "what does this do" comment, I try to
re-write the code to be easier to read. Normally that means breaking
it into smaller pieces, and using static inline functions with clear
I try to only write comments which either explain "why" (historical
information, bug links, etc.) or FIXME's explaining "what" the code
should do in the future.
On Thu, Jan 27, 2011 at 3:40 PM, Dirk Pranke <dpranke at chromium.org> wrote:
> Hi all,
> Have there been any threads or blog posts in the past over an
> appropriate level of comments in the code? A brief search of the
> Google and the list archives didn't really turn up anything.
> >From what I've seen, code in WebKit is much less commented than most
> if not all large projects I've worked on. Is this intentional? If so,
> why? Also, do we want commenting style to be consistent across
> languages in the project?
> For example, Python code is usually pretty well commented, but we've
> checked in some Python files here with almost no comments, with the
> rationale being that "it's WebKit style".
> To allay any fears, I'm not suggesting that we should have large
> chunks of boilerplate or anything like that. I'm aware as anybody of
> the danger of comments being wrong or getting out of sync with the
> -- Dirk
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
More information about the webkit-dev