On Wed, Mar 21, 2012 at 2:41 PM, David Levin <levin@chromium.org> wrote:

I think the challenge in part is to explain why the ChangeLog is useful.

Comments in there hopefully explain why as a guide to reviewers to give the reviewers and future onlookers a guide to the change.

I do agree that "why" comments are more useful than "what" comments are most cases.

However, I'd say it's also helpful to summarize what a new function / class does as well if the patch adds one. Since comments in the change log is for a specific revision unlike comments in the code, it's less dangerous to add "what" comment.

- Ryosuke