[parted-devel] [PATCH] next branch

[Joel Granados]

On Tue, May 26, 2009 at 03:16:35PM +0200, Jim Meyering wrote:
> 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.

True, the git log is not modifyable but we should not be allowing
inaccurate descriptions anyway.  If the description is inacurate, the
patch should be rejected.
You are also correct when you assume that the description might
become inaccurate when someone changes the function in the future.
But I would still argue that a small description is needed when the
function name leaves some obvious unanswered questions.  These, of
course, are situations that must be evaluated per commit.

> 
> 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.

With this comment I have an opinion and a question:

Question:  One rights documentation of a function when the function is
not obvious and when the function is part of the library.  right?
More specifically, What are the policies for documenting a function?

Opinion:  I think that there are various resons for not documenting
a function.  Placing a short "doubt resolving" comment in the commit, is
not one of the main ones.  I would argue that not knowing the policy
would be a major reason (from the patch creator and from the patch
reviewer).  Also, laziness, lack of time also pop into my mind as
reasons that would come before being lulled by the commit message.  I
would further argue that with the correct knowledge of when to document
a function, the reviewer would easily detect when a patch needs to add
documentation.


Regards.


-- 
Joel Andres Granados
Brno, Czech Republic, Red Hat.