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

[Per Bothner]

On 07/06/2012 03:49 PM, Ryosuke Niwa wrote:
>> If nothing else
>> it's a useful sanity check: If something changes enough that you need to
>> change a comment, that suggests it's a good thing to take the time to
>> think through the implications well enough to write them down.
>
> We do that in change logs.

Again: Differing cultures - it seems like WebKit treats change log
comments as more important than I'm used to in other projects.
I would never expect to read ChangeLog to get at the big picture;
you'd get drowned in a mass of details, and changes that get reverted.
I'd read ChangeLog s to answer a particular question like: is it
deliberate that the code does this, and why.  Though again, I'm used
to the philosophy that if the code is obvious, don't comment, but if
it is non-obvious explain why - in the code.  That's where it is more
likely to be correct, and more likely to updated when something changes.

But I guess most of WebKit is relatively simple compared to (for example)
the compilers that I've mostly worked on.
-- 
	--Per Bothner
per.bothner at oracle.com   per at bothner.com   http://per.bothner.com/