* ChangeLog or not? [not found] <E1S3y4u-0008Fx-4B@vcs.savannah.gnu.org> @ 2012-03-06 17:33 ` Ludovic Courtès 2012-03-06 18:13 ` Mark H Weaver 0 siblings, 1 reply; 5+ messages in thread From: Ludovic Courtès @ 2012-03-06 17:33 UTC (permalink / raw) To: guile-devel 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’. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: ChangeLog or not? 2012-03-06 17:33 ` ChangeLog or not? Ludovic Courtès @ 2012-03-06 18:13 ` Mark H Weaver 2012-03-06 20:39 ` Andy Wingo 2012-03-06 23:17 ` Ludovic Courtès 0 siblings, 2 replies; 5+ messages in thread From: Mark H Weaver @ 2012-03-06 18:13 UTC (permalink / raw) To: Ludovic Courtès; +Cc: guile-devel 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 ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: ChangeLog or not? 2012-03-06 18:13 ` Mark H Weaver @ 2012-03-06 20:39 ` Andy Wingo 2012-03-06 23:17 ` Ludovic Courtès 1 sibling, 0 replies; 5+ messages in thread From: Andy Wingo @ 2012-03-06 20:39 UTC (permalink / raw) To: Mark H Weaver; +Cc: Ludovic Courtès, guile-devel 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/ ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: ChangeLog or not? 2012-03-06 18:13 ` Mark H Weaver 2012-03-06 20:39 ` Andy Wingo @ 2012-03-06 23:17 ` Ludovic Courtès 2012-03-07 9:54 ` Andy Wingo 1 sibling, 1 reply; 5+ messages in thread From: Ludovic Courtès @ 2012-03-06 23:17 UTC (permalink / raw) To: Mark H Weaver; +Cc: Andy Wingo, guile-devel 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’. ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: ChangeLog or not? 2012-03-06 23:17 ` Ludovic Courtès @ 2012-03-07 9:54 ` Andy Wingo 0 siblings, 0 replies; 5+ messages in thread From: Andy Wingo @ 2012-03-07 9:54 UTC (permalink / raw) To: Ludovic Courtès; +Cc: Mark H Weaver, guile-devel 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/ ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2012-03-07 9:54 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- [not found] <E1S3y4u-0008Fx-4B@vcs.savannah.gnu.org> 2012-03-06 17:33 ` ChangeLog or not? Ludovic Courtès 2012-03-06 18:13 ` Mark H Weaver 2012-03-06 20:39 ` Andy Wingo 2012-03-06 23:17 ` Ludovic Courtès 2012-03-07 9:54 ` Andy Wingo
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).