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

From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Jun 18, 2021, 07:24 UTC
Message-ID: <87wnqr4n0i.fsf@evledraar.gmail.com>
In-Reply-To: <YMvuprVu1MnokHM5@camp.crustytoothpaste.net>

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

Show 20 quoted lines

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

Show 8 quoted lines

> [...]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/