Hi! On Fri, 9 Sep 2011 10:14:10 +0200, <olafbuddenha...@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
pgp2ULuSHBsSa.pgp
Description: PGP signature
