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

[Felipe Contreras <felipe.contreras@gmail.com>]

Junio C Hamano wrote:

> -  - Removing the example person might make the sentence more
> -    clear and efficient.  Instead of saying "The programmer
> -    chooses between X and Y as she sees fit", it is clearer to
> -    say "Valid choices are X and Y".
> -
> -  - If you need to talk about an example person, then try using
> -    second-person to allow the reader to be that example.  For
> -    example, "If you want X to happen, you'd pass option Y",
> -    instead of "If the user wants X to happen, she'd ...").
> -    Alternatively, replace the single example with more than one
> -    person and use plural "they", such as "Interested readers
> -    can read 'git log -p README' to learn the history in their
> -    ample spare time" instead of "an interested reader" learning
> -    in "his" spare time).
> -
> -  - If you absolutely need to refer to an example person that is
> -    third-person singluar, you may resort to "singular they" (e.g.
> -    "A contributor asks their upstream to pull from them").

Here is another escape hatch recommended by linguists before attempting
to use singular "they":

 - Use a generic alternative and count on the reader's common sense.
   Instead of saying "she made a mistake", say "a mistake was made".

> -    Note
> -    that this sounds ungrammatical and unnatural to those who
> -    learned English as a second language in some parts of the
> -    world, so should be avoided unless the earlier techniques
> -    fail to improve the sentence.

For the nth time, it's not just foreign speakers:

https://ahdictionary.tumblr.com/post/147597257733/updated-usage-note-they

> +  - Prefer succinctness and matter-of-factly describing functionality
> +    in the abstract.  E.g.
> +
> +     --short:: Emit output in the short-format.
> +
> +    and avoid something like these overly verbose alternatives:
> +
> +     --short:: Use this to emit output in the short-format.
> +     --short:: You can use this to get output in the short-format.
> +     --short:: A user who prefers shorter output could....
> +     --short:: Should a person and/or program want shorter output, he
> +               she/they/it can...
> +
> +    This practice often eliminates the need to involve human actors in
> +    your description, but it is a good practice regardless of the
> +    avoidance of gendered pronouns.
> +
> +  - When it becomes awkward to stick to this style, prefer "you" when
> +    addressing the the hypothetical user, and possibly "we" when
> +    discussing how the program might react to the user.  E.g.
> +
> +      You can use this option instead of --xyz, but we might remove
> +      support for it in future versions.
> +
> +    while keeping in mind that you can probably be less verbose, e.g.
> +
> +      Use this instead of --xyz. This option might be removed in future
> +      versions.
> +
> +  - If you still need to refer to an example person that is
> +    third-person singular, you may resort to "singular they" to avoid
> +    "he/she/him/her", e.g.
> +
> +      A contributor asks their upstream to pull from them.
> +
> +    Note that this sounds ungrammatical and unnatural to those who
> +    learned English as a second language in some parts of the world.

These look OK to me, but I wonder why we have writing tips in *coding*
guidelines.

We are not writing a style manual, there's plenty of other tips writers
of documentation, commit messages and comments could use, why are we
only giving tips for gender pronouns?

Why don't we have a section on passive vs. active voice? How about
avoiding zombie nouns? Adjectives and adverbs? That vs. which? Who and
whom?

I don't think there's much value in trying to codify what is a good
sense of style while writing just for one particular non-issue.

Cheers.

-- 
Felipe Contreras