[webkit-dev] Please include function-level comments in change log entries

[Konrad Piascik]

I find that the function level comments, while potentially more time consuming to create are more beneficial than the comments at the top. It makes it not only easier to review but for also when going through the history and trying to see what changes were made.

About iterations of the changelog during review updating the log at the top or at the function level (once the comments are already in place) should be an equivalent amount of time, at least in my experience.
Konrad
Sent from my BlackBerry on the Rogers Wireless Network

From: Dana Jansens [mailto:danakj at chromium.org]
Sent: Friday, July 06, 2012 02:42 PM
To: Dan Bernstein <mitz at apple.com>
Cc: WebKit Development <webkit-dev at lists.webkit.org>
Subject: Re: [webkit-dev] Please include function-level comments in change log entries

On Fri, Jul 6, 2012 at 1:05 PM, Dan Bernstein <mitz at apple.com<mailto:mitz at apple.com>> wrote:
It appears that lately most WebCore change log entires don’t include any comments on individual functions. An overall description of the change at the top of the change log entry is valuable, but it is no substitute for describing the changes to each function. Good function-level comments are useful both while reviewing a patch and while revisiting existing code. Personally, I find that writing the function-level comments helps me a lot in reviewing my own patches before I post them.

I find that the overhead of maintaining comments outside of the top of the changelog is excessive. Every time I change a patch in a non-trivial way during the review process, I must regenerate the changelogs. Copy/paste/edit the description at the top is not unreasonable. Hand-merging my old changelog with the new one for each method becomes an egregious amount of work. And I don't see how it helps review more than a proper description at the top that mentions the methods of interest as appropriate.


Thanks.
_______________________________________________
webkit-dev mailing list
webkit-dev at lists.webkit.org<mailto:webkit-dev at lists.webkit.org>
http://lists.webkit.org/mailman/listinfo.cgi/webkit-dev


---------------------------------------------------------------------
This transmission (including any attachments) may contain confidential information, privileged material (including material protected by the solicitor-client or other applicable privileges), or constitute non-public information. Any use of this information by anyone other than the intended recipient is prohibited. If you have received this transmission in error, please immediately reply to the sender and delete this information from your system. Use, dissemination, distribution, or reproduction of this transmission by unintended recipients is not authorized and may be unlawful.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.webkit.org/pipermail/webkit-dev/attachments/20120706/86bf0191/attachment.html>