Re: ChangeLog or not?

[Mark H Weaver]

Hi Ludovic!

address@hidden (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