[parted-devel] [PATCH] next branch

[Jim Meyering]

Joel Granados wrote:
>> Regarding the logs,
>> when you add a new function, just saying "New function."
>> is enough, because there has to be a comment in the
>> code already saying what the function does.
>
> This is true. But I have to insist on a small description, instead of
> just saying "New function" as the diff that accompanies the commit might
> not be as readable or as obvious.  With that said, I'm OK with that
> change.

The name is there already.
I hope that's enough for you, in general

It's better not to describe it at all in the commit log).
Otherwise, you risk someone reading and relying on that abbreviated
(or maybe inaccurate) description.  In addition, with any duplication
at all, you'd want to keep them in sync, but the git log is not
modifiable.

Also, it's best to avoid putting too much per-function
description in the log, because that could lull the author
into thinking s/he has already written the required
documentation, without realizing that it was solely
for the log, and not yet made into the mandatory
function-describing comment.