Re: [PATCH v3 2/3] CodingGuidelines: hint why we value clearly written log messages

[Junio C Hamano <gitster@pobox.com>]

Junio C Hamano <gitster@pobox.com> writes:

> Emily Shaffer <emilyshaffer@google.com> writes:
>
>>> + - Log messages to explain your changes are as important as the
>>> +   changes themselves.  Clearly written code and in-code comments
>>> +   explain how the code works and what is assumed from the surrounding
>>> +   context.  The log messages explain what the changes wanted to
>>> +   achieve and why the changes were necessary (more on this in the
>>> +   accompanying SubmittingPatches document).
>>> +
>>
>> One thing not listed here, that I often hope to find from the commit
>> message (and don't), is "why we did it this way instead of <other way>".
>> I am not sure how to phrase it in this document, though. Maybe:
>>
>>   The log messages explain what the changes wanted to achieve, any
>>   decisions that were made between alternative approaches, and why the
>>   changes were necessary (more on this in blah blah)
>>
>> Or maybe "...whether any alternative approaches were considered..." fits
>> the form of the surrounding sentence better.
>
> Quite valid observation.
>
> Documentation/SubmittingPatches::meaningful-message makes a note on
> these points, and the above may want to be more aligned to them.
>
> Patches welcome, as these have long been merged to 'master/main'.

Another thing.  If you (not Emily, but figuratively) haven't watched
Victoria's talk https://www.youtube.com/watch?v=4qLtKx9S9a8 on the
topic of clearly written commits, you should drop everything you are
doing and go watch it.

And with what we learn from it, we may be able to rewrite this part
of the documentation much more clearly.