On Jan 30, 2011, at 4:41 PM, Ryan Leavengood wrote: > On Sunday, January 30, 2011, Maciej Stachowiak <m...@apple.com> wrote: >> >> I'll go the other way and point out some example of comments that I think >> are poor. > > This file is terribly commented, I agree, but cherry picking a really > bad file isn't the best way to make a point IMO.
Well, I didn't mean to pick on the authors of this file. This is the impression I get from a lot of code that some call "well-commented", by which they mean "lots of comments". > Maybe the solution here is better documentation outside the source > code. I hope some of the more experienced WebKit developers can agree > that there are parts of the code that are harder for new developers to > dig into. Some high-level docs that are kept updated might be nice. Of > course the key here is keeping them updated, and if it is hard to keep > source code comments up to date I don't know how much hope there is > for outside docs. Of course this applies to any project and is by no > means just a flaw in this project. At least if the comments are in the > code there is hope that a reviewer would catch when comments get out > of date. I agree that high-level docs would be useful. It's hard to make good ones. My favorite two kinds of non-source-code documentation are explanations of common idioms (e.g. <http://webkit.org/coding/RefPtr.html>) and explanations of how large-scale subsystems relate to each other. These types of documentation are somewhat less likely to go out of date than function-level or even class-level comments. Often, the best place for them is not in the code. Though it might be a good comprehensive guide to WebKit development that collects the more useful documentation we have. Regards, Maciej
_______________________________________________ webkit-dev mailing list webkit-dev@lists.webkit.org http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev
