Re: Using VC for change descriptions

[Joseph Myers]

On Tue, 28 Nov 2017, John Darrington wrote:

> I have had this conversation with a few people in the past, and some have 
> suggested "put the reason in a comment in the source code".  But this
> suggestion is rather naive.  A single change could affect many files and
> dozens of functions (for example it might change a function parameter from
> pass by value to pass by pointer - which would have a knock-on effect for
> all contained functions)  It would be simply rediculous to put a comment
> next to every use of the variable saying: 
>   /* This used to be a char - now it is a pointer to char, because ... */

Furthermore, comments in the source code about why it does something are 
comments explaining things that are nonobvious about the current state of 
the source code, e.g. why a particular special case is needed.  They are 
not about how it got there.  Whereas a commit message explanation of "why" 
is an explanation of the reason for a change, relative to the previous 
version of the source code.  A commit message can explain why something 
was removed, when there may be no sensible place in the source code for 
such an explanation, as well as explaining the reason for something global 
such as you mention.

Nothing in my proposal changes anything about when there should be 
comments in the source code to help people understand the current state of 
the code without needing to refer to its history.  But there are still 
cases where it's appropriate for the commit message to include information 
about "why" that doesn't naturally fit in the source code, and vice versa.

-- 
Joseph S. Myers
address@hidden