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

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

Emily Shaffer <emilyshaffer@google.com> writes:

> 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.

> 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.