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