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

[Emily Shaffer <emilyshaffer@google.com>]

On Thu, Jan 27, 2022 at 11:02:58AM -0800, Junio C Hamano wrote:
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> ---
>  Documentation/CodingGuidelines | 7 +++++++
>  1 file changed, 7 insertions(+)
> 
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> index 0e27b5395d..c37c43186e 100644
> --- a/Documentation/CodingGuidelines
> +++ b/Documentation/CodingGuidelines
> @@ -26,6 +26,13 @@ code.  For Git in general, a few rough rules are:
>     go and fix it up."
>     Cf. http://lkml.iu.edu/hypermail/linux/kernel/1001.3/01069.html
>  
> + - 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.

 - Emily

>  Make your code readable and sensible, and don't try to be clever.
>  
>  As for more concrete guidelines, just imitate the existing code
> -- 
> 2.35.0-177-g7d269f5170
>