Problem/Motivation

Hi

Do we need a small sentence in http://drupal.org/node/1354 about the use of "We" vs "I" in Drupal core comments? There are 1741's "we"-s and two "I"-s in all the comments of Drupal core 7.4. So "we" are nearly doing it all right. But we might need to spend a sentence on it to help new people and have a clear guideline, under http://drupal.org/node/1354#general like

"We use "We" as a personal pronoun instead of I". For example
// Verify that we are still logged in.
instead of
// I want a custom canonical url.
"

Thoughts? Over-documenting? wrding?

Use links

Benefits

If we adopted this change, the Drupal Project would benefit by ...

Three supporters required

  1. https://www.drupal.org/u/{userid} (yyyy-mm-dd they added support)
  2. https://www.drupal.org/u/{userid} (yyyy-mm-dd they added support)
  3. https://www.drupal.org/u/{userid} (yyyy-mm-dd they added support)

Proposed changes

Provide all proposed changes to the Drupal Coding standards. Give a link to each section that will be changed, and show the current text and proposed text as in the following layout:

1. Drupal API documentation standards (general)

Current text

There are no recommendations on the use of pronouns.

Proposed text

Do not use gender specific pronouns.

2. Repeat the above for each page or sub-page that needs to be changed.

Remaining tasks

  1. Create this issue in the Coding Standards queue, using the defined template
  2. Add supporters
  3. Create a Change Record
  4. Review by the Coding Standards Committee
  5. Coding Standards Committee takes action as required
  6. Discussed by the Core Committer Committee, if it impacts Drupal Core
  7. Final review by Coding Standards Committee
  8. Documentation updates
    1. Edit all pages
    2. Publish change record
    3. Remove 'Needs documentation edits' tag
  9. If applicable, create follow-up issues for PHPCS rules/sniffs changes

For a full explanation of these steps see the Coding Standards project page

Comments

silverwing’s picture

silverwing commented
Project: Drupal.org site moderators » Documentation
Component: Other » Correction/Clarification
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Title: Use of "We" and "I" in comments in code to be described in handbook » [policy, no patch] Standard: Use of "We" and "I" in comments in code
Project: Documentation » Drupal core
Version: » 8.x-dev
Component: Correction/Clarification » documentation
Category: feature » task
Priority: Minor » Normal
Issue tags: +Coding standards

Interesting idea... maybe we should avoid personal pronouns altogether?

Moving this to the Drupal Core queue, which is where we discuss coding (and comment) standards.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Project: Drupal core » Drupal Technical Working Group
Version: 8.0.x-dev »
Component: documentation » Documentation
Issue summary: View changes

Coding standards decisions are now supposed to be made by the TWG

douggreen’s picture

douggreen commented

I try to avoid personal pronouns in comments altogether, so no usages of "You", "I", or "We". Comments are not novels with actors. They are documentation on what something does, not on what the (gender neutral) actors do.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented

People often use "we" in in-code comments though, and actually for UI documentation, "you" is a usability plus, and I think that would also apply to documentation aimed at developers, such as "You need to ... in order to ...".

So I am not convinced we should define a standard either advocating or forbidding this.

joachim’s picture

joachim commented

I tend to use 'we' if I want to speak from the POV of the code. For me at least, it's a habit that dates back to showing my working in maths, eg 'We factorise the expression in order to use integration by parts.'. So in code, something like 'We first try to check the user's permission, and then fall back on yada yada.'

And for documentation addressed to the developer, 'You should ensure to sanitize this output' is more readable than something like 'Developers should ensure ...'.

damienmckenna’s picture

damienmckenna
Location TN, USA
commented

I thought using pronouns was a standard documentation no-no? Are there other documentation standards that may be drawn upon here?

tizzo’s picture

tizzo commented
Project: Drupal Technical Working Group » Coding Standards

Moving this issue to the Coding Standards queue per the new workflow defined in #2428153: Create and document a process for updating coding standards.

quietone’s picture

quietone commented
Issue summary: View changes
quietone’s picture

quietone commented
Title: [policy, no patch] Standard: Use of "We" and "I" in comments in code » Standard: Use of "We" and "I" in comments in code
quietone’s picture

quietone commented
Issue summary: View changes

I did some more duck-duck-going and didn't find a reference with clear guidance for technical writing about 'we' and 'I'. 'We' is definitely used most frequently in core. And the usages of 'I' are minimal, less that 13. And of those two are for agreeing to terms and conditions. Skimming the others I only see one usage in core/modules/views/src/Plugin/views/display/DisplayPluginBase.php in a comment that could be changed. But even that is very minor.

I'd rather not add a statement about standardizing on 'We' because we seem to be dong fine as is. And I would want to encourage the usage when it is often better to simply declare or explain something.

So, this could be a won't fix and we move the gendered pronoun discussion to a new issue. Or re-title this one.

quietone’s picture

quietone commented
Issue summary: View changes

Also, I didn't find any usages of he or she in core that should to change.

quietone’s picture

quietone commented
Status: Active » Needs review
bbrala’s picture

bbrala
Location Netherlands
commented

If currently we are not fixing an issue, or something very minimal, i agree we should not do it and keep things as simple as possible.

bbrala’s picture

bbrala
Location Netherlands
commented
Status: Needs review » Closed (won't fix)

As discussed in the coding standard meeting of 22th of may, since there is not more activity we are closing this for now.