ChangeLog or not?

ChangeLog or not?

[Ludovic Courtès]

Hello!

I sympathize with the idea of ChangeLogs as in the GCS (info
"(standards) Change Log Concepts"), and in particular:

     There's no need to describe the full purpose of the changes or how
  they work together.  However, sometimes it is useful to write one line
  to describe the overall purpose of a change or a batch of changes.  If
  you think that a change calls for explanation, you're probably right.
  Please do explain it--but please put the full explanation in comments
  in the code, where people will see it whenever they see the code.  For
  example, "New function" is enough for the change log when you add a
  function, because there should be a comment before the function
  definition to explain what it does.

I think it makes it easier to review patches, and to understand the code.

Alas, that convention is not widely followed in Guile.  I really think
it makes a lot of sense though, and would love to see us use it more.

WDYT?  Are you more comfortable with the opposite approach?
Do you think it’s bikeshedding?  :-)

Thanks,
Ludo’.

Re: ChangeLog or not?

[Mark H Weaver]

Hi Ludovic!

ludo@gnu.org (Ludovic Courtès) writes:
> I sympathize with the idea of ChangeLogs as in the GCS (info
> "(standards) Change Log Concepts"), and in particular:
>
>      There's no need to describe the full purpose of the changes or how
>   they work together.  However, sometimes it is useful to write one line
>   to describe the overall purpose of a change or a batch of changes.  If
>   you think that a change calls for explanation, you're probably right.
>   Please do explain it--but please put the full explanation in comments
>   in the code, where people will see it whenever they see the code.  For
>   example, "New function" is enough for the change log when you add a
>   function, because there should be a comment before the function
>   definition to explain what it does.
>
> I think it makes it easier to review patches, and to understand the code.
>
> Alas, that convention is not widely followed in Guile.  I really think
> it makes a lot of sense though, and would love to see us use it more.
>
> WDYT?  Are you more comfortable with the opposite approach?

I agree with you.  While I see nothing inherently wrong with verbose
commit logs, in practice this tends to come at the expense of comments
in the code itself, and that is a very serious problem.

I admit that I tend to fall into this pattern myself.  I often write
code with almost no comments, and think about documentation only when it
comes time to present my patches to the mailing list.  This naturally
leads to many of my higher-level descriptions ending up in the commit
logs, or even worse, in my emails to the mailing list and nowhere else.

Thanks to your periodic reminders, I'm increasingly attempting to catch
myself in this bad pattern.  The code should speak for itself.  If it
requires an external explanation, then that's a problem.

> Do you think it’s bikeshedding?  :-)

Not at all!  Thank you for nudging us in the direction of better code
comments, regression tests, etc.  These are very important for Guile's
long-term health.

   Best,
    Mark

Re: ChangeLog or not?

[Andy Wingo]

On Tue 06 Mar 2012 19:13, Mark H Weaver <mhw@netris.org> writes:

>>   but please put the full explanation in comments
>>   in the code, where people will see it whenever they see the code.
>
>> Do you think it’s bikeshedding?  :-)
>
> Not at all!  Thank you for nudging us in the direction of better code
> comments, regression tests, etc.  These are very important for Guile's
> long-term health.

I agree in general.

I wonder though about some specific cases.  For example,
performance-related changes.  Justifying performance improvements
necessarily depends on a description of two different revisions of a
piece of functionality -- and there's no sense for describing an
interface that's not there any more.  For a change motivated by
performance, then, I would expect to see more in the change log than in
the comments.

Similarly for "X is temporarily moved to Y but will be moved to Z in a
future commit".

There are probably other cases.  Dunno, perhaps I have not yet been
fully indoctrinated :-)

Andy
-- 
http://wingolog.org/

Re: ChangeLog or not?

[Ludovic Courtès]

Hi!

Mark H Weaver <mhw@netris.org> skribis:

> I agree with you.  While I see nothing inherently wrong with verbose
> commit logs, in practice this tends to come at the expense of comments
> in the code itself, and that is a very serious problem.

Yes, exactly.

In addition, there’s value IMO in having change logs be exactly that: a
log of changes made to the source code’s AST.  This tells how the
changes were implemented (useful when reviewing), while the comments
and/or posts would explain why.

Andy Wingo <wingo@pobox.com> skribis:

> I wonder though about some specific cases.  For example,
> performance-related changes.  Justifying performance improvements
> necessarily depends on a description of two different revisions of a
> piece of functionality

Not necessarily.  The source code could have a comment close to the data
structure, algorithm, etc. that would say “this is done this way because
it has such and such nice performance characteristics.”

The advantage is that future readers would notice and have those
concerns in mind when touching the code.

[...]

> Similarly for "X is temporarily moved to Y but will be moved to Z in a
> future commit".

I can’t really see what that pattern would be.

Anyway, there are surely exceptions, but I think the basic rationale
holds most of the time.

> There are probably other cases.  Dunno, perhaps I have not yet been
> fully indoctrinated :-)

I actually view the change log chapter of the GCS as a rational
justification of the practice, more than as a a doctrine.  :-)

Thanks,
Ludo’.

Re: ChangeLog or not?

[Andy Wingo]

On Wed 07 Mar 2012 00:17, ludo@gnu.org (Ludovic Courtès) writes:

>> Dunno, perhaps I have not yet been fully indoctrinated :-)
>
> I actually view the change log chapter of the GCS as a rational
> justification of the practice, more than as a a doctrine.  :-)

Sure.  I just meant that I also program in some non-GNU environments
with strong (and different) coding conventions, so sometimes my brain is
a bit mixed up.  So for Guile, your continued reminders are much
appreciated :-)

Cheers,

Andy
-- 
http://wingolog.org/