[webkit-dev] coding style and comments

[Eric Seidel]

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
names.

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.

-eric

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
> code.
>
> -- Dirk
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
>