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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 20, 2022, 08:23 UTC
Message-ID: <xmqqbkwwrwn7.fsf@gitster.g>
In-Reply-To: <Yl89hMGLN3DqIkJ7@google.com>

Emily Shaffer <emilyshaffer@google.com> writes:

Show 5 quoted lines

> On Thu, Apr 14, 2022 at 04:04:59PM +0200, Ævar Arnfjörð Bjarmason wrote:
>>  ...
>> For our CodingGuidelines I think it would be useful to have some version
>> of "if you can explain something with prose or tests, prefer
>> tests".

I was going to ignore this part as it is merely showing personal preference, but I guess I need to weigh in here.

Demonstrating what you meant to say in the log message with tests is fine, but that should be in addition to prose, explaining how the scenario is set up and what the user wanted to do, before showing that a command is giving an outcome that does not help what the user wanted to do.

IOW, in our CodingGUidelines, we should have "tests can be a good way to augument what you want to say, but explain it well to those who are not so familiar with the area." You do not necessarily have to explain it to 5 year old, but the audience should not have to be whoever writes the patch themself to understand it.

Show 5 quoted lines

> So as I'm deciding what to review, I definitely would prefer Victoria's
> commit message. Plus, like I mentioned, it gives the extra safeguard of
> allowing reviewers to check: does the patch actually do what the author
> meant for it to do? If we're never told what the author meant for it to
> do, then we are missing information needed for that part of the review.

I have nothing to add here.

> Anyway, I haven't watched Victoria's talk yet, but I will do so soon :)

I do not necessarily agree with the presentation order in a proposed log message she suggests, but overall, it's good investment of your time. Highly recommended.