Re: [PATCH v3 4/4] CodingGuidelines: recommend singular they

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Fri, Jun 18 2021, brian m. carlson wrote:

> [[PGP Signed Part:Undecided]]
> On 2021-06-16 at 19:54:20, Ævar Arnfjörð Bjarmason wrote:
>> The references to "gendered prounouns" etc. are gone, perhaps there's a
>> good reason to re-include them, but the point of "isn't that issue
>> solved by recommending an orthagonal approach?" is one of the many
>> things Stolee hasn't been addressing in the threads related to this
>> series.
>
> I think I've addressed this.  Sometimes you can avoid referring to
> people and therefore avoiding pronouns, and sometimes the prose reads
> better if you talk about the user or actor.  Also, sometimes you need to
> discuss a matter at length and using variety in your language is
> desirable, so you may want to, for example, avoid continually using the
> passive voice to discuss the topic.
>
> I don't think it's fair to just say "don't refer to the user or other
> humans if you'd need to use third-person pronouns" because I don't think
> that's applicable in all cases.  I, for one, don't intend to write my
> commit messages in that way because I think it will make them
> substantially worse.

You won't have to. Reading this and your slightly earlier
<YMvoNcFXnHo0KXH3@camp.crustytoothpaste.net> I think you've missed that
as of v2[1] of this series the proposal to is not to enforce this policy
on people's commit messages; so we're only talking about code comments
and documentation at this point.

> [...]For example, I often discuss the behavior or
> expectations of users when writing FAQ entries or other documentation
> and sometimes we'll need to use pronouns.
>
> I agree that in many cases we can effectively rephrase to avoid needing
> to do this, but if we acknowledge that sometimes we will need to write
> using third-person personal pronouns in some cases, it's worth
> documenting what those should be.

I agree with you as a general matter that anything we come up with,
whether it's a prose guideline, coding style etc. won't cover all
cases.

But perhaps we disagree on whether that should be a goal of our
guidelines at all. I don't think it should. It shouldn't because it
simply won't work, the amount of guidelines we ask contributors to read
becomes a zero-sum game at some point.

Assuming that most contributors attempt to at least skim them we've
already reached that point. It's a trivial task to find recent
submissions of patches that violate one guideline or another.

So the criteria for inclusion shouldn't be whether we can think of cases
they apply to, but whether those cases are common enough to warrant
explicit mention, keeping in mind that any new addition will dilute
whatever advice we're already giving. Having gone over the number of
occurances we're fixing [2] I don't see how this qualifies.

As Stolee said upthread[3], referring to Documentation/CodingGuidelines
("[]" edits of what I understood him to mean are mine):

    [It's the document that we] should just be able to point to [say] "here
    is the decision we made"

I just don't think that should be a primary or secondary goal of that
document. We have e.g. this mailing list discussion to point to for some
decision we made.

The CodingGuidelines is what we're asking people to read when they've
e.g. found some data-eating bug in git and are about to send us a patch,
but before that we're asking them to go through a fuzzy checklist of
items checklist. It's already 20 pages in my browser if I were to try to
print it.

1. https://lore.kernel.org/git/pull.975.v2.git.1623246878.gitgitgadget@gmail.com/
2. https://lore.kernel.org/git/87o8c4wkn7.fsf@evledraar.gmail.com/
3. https://lore.kernel.org/git/5755690e-ef13-e12c-4b10-9cb303ae843a@gmail.com/