Re: ChangeLog/commit messages

[Thomas Schwinge]

Hi!

On Fri, 9 Sep 2011 10:14:10 +0200, <olafBuddenhagen@gmx.net> wrote:
> On Wed, Sep 07, 2011 at 05:06:09PM +0200, Thomas Schwinge wrote:
> 
> > On the other hand, comments such as Olaf's quoted above (``Instead of
> > [...]'') should in fact not be put into the ChangeLog/commit message,
> > but should be put (in a slightly altered form, of course) into the
> > code itself: to describe the logic/where the 10000 constant is coming
> > from.
> 
> Well, that's what the GCS says... But it's one of the portions of GCS I
> do not entirely agree this. Of course code should come with comments
> explaining it -- but I don't think the particular line I changed here
> needs much explanation. (Though the formatting code could do with a bit
> more explanation in general I guess...)
> 
> Note that my explanation in the commit message is mostly about why I
> found the *previous* code not to be optimal... It would be rather
> inappropriate to put it next to the new code IMHO.

Ack; that's what I meant with putting it there ``in a slightly altered
form, of course'': no need to talk about the past in the current code.

> The commit message on the other hand is where people generally look when
> they want to understand *why* things changed. That's where such
> explanations are useful.

Ack; but before looking at any changes, people will first look at the
current code and gain knowledge of the *current* state.  And if in there
they read a source code comment that the value 10000 is used because of
[...], then any past change to this value that they see in the commit
history will make sense; especially so the one that introduced the
comment.

But, for me it is more helpful to directly see in the *current* code the
reasoning behind it, without having to consult the commit log.  For
example, while browsing the source code, if I were curious about this
10000 value, I'd have to look at git annotate (or a similar tool), locate
the commit that changed this value, and hope to find some information in
the commit log.

Of course, this has to be decided on a case by case basis.

> Note that with the exception of a few old GNU programs, pretty much
> *every* project I ever looked at follows this approach -- including huge
> ones such as Linux or X.Org.


> > (Olaf, as you've already seen, this does give me the power to assign
> > Savannah tasks to you.)  ;-P
> 
> And as I'm a volunteer, I retain the power to ignore this ;-P

;-)


Grüße,
 Thomas

pgpCLqOPitsgs.pgp
Description: PGP signature