Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: improve formatting of STYLE_GUIDE.md #13135

Closed
wants to merge 2 commits into from
Closed

doc: improve formatting of STYLE_GUIDE.md #13135

wants to merge 2 commits into from

Conversation

aqrln
Copy link
Contributor

@aqrln aqrln commented May 20, 2017

  • Wrap text at 80 characters.
  • Use periods consistently.
Checklist
Affected core subsystem(s)

doc

@aqrln
doc: improve formatting of STYLE_GUIDE.md
19efac2 
* Wrap text at 80 characters.
* Use periods consistently.
@nodejs-github-bot nodejs-github-bot added the doc Issues and PRs related to the documentations. label May 20, 2017
Trott
Trott approved these changes May 21, 2017
View reviewed changes
Copy link
Member

@Trott Trott left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great. LGTM. Thanks for doing this. I left a bunch of nits, but I'm fine with this landing even if none of them get addressed. This PR is a clear improvement as-is over the current doc. Thanks again!

doc/STYLE_GUIDE.md Outdated
* Pronouns are acceptable in more colloquial documentation, like guides.
* Use **gender-neutral pronouns** and **mass nouns**. Non-comprehensive
examples:
* **OK**: "they", "their", "them", "folks", "people", "developers", "cats"
* **OK**: "they", "their", "them", "folks", "people", "developers", "cats".
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: This line and the following line probably shouldn't end with periods because they are not sentences. They are just lists. I'm OK with using a period anyway for consistency or simplicity, but I do have a slight preference for leaving the period off in this case.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I wasn't sure about these. They look a bit more natural without periods.

doc/STYLE_GUIDE.md Outdated
* References to constructor functions should use PascalCase
* References to constructor instances should be camelCased
* References to methods should be used with parentheses: `socket.end()` instead of `socket.end`
* When using underscores, asterisks and backticks please use proper escaping
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: While we're in here, can you add a comma after asterisks and backticks. (Kind of funny that this very guide recommends using a serial comma and then misses one right here!)

doc/STYLE_GUIDE.md Outdated
* When using underscores, asterisks and backticks please use proper escaping
(**\\\_**, **\\\*** and **\\\`** instead of **\_**, **\*** and **\`**).
* References to constructor functions should use PascalCase.
* References to constructor instances should be camelCased.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: be camelCased -> use camelCase

That will be consistent with the previous line and avoid awkwardly using camelCase as a verb.

doc/STYLE_GUIDE.md Outdated
(**\\\_**, **\\\*** and **\\\`** instead of **\_**, **\*** and **\`**).
* References to constructor functions should use PascalCase.
* References to constructor instances should be camelCased.
* References to methods should be used with parentheses: `socket.end()` instead
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: While we're in here, add for example, after the colon.

cjihrig
cjihrig approved these changes May 21, 2017
View reviewed changes
Copy link
Contributor

@cjihrig cjihrig left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM with @Trott's nits addressed.

mhdawson
mhdawson approved these changes May 23, 2017
View reviewed changes
Copy link
Member

@mhdawson mhdawson left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@mhdawson
Copy link
Member

CI run: https://ci.nodejs.org/job/node-test-pull-request/8256/

@addaleax
Copy link
Member

LGTM

Landed in eebc262

@addaleax addaleax closed this May 23, 2017
addaleax pushed a commit that referenced this pull request May 23, 2017
@aqrln @addaleax
doc: improve formatting of STYLE_GUIDE.md
eebc262 
* Wrap text at 80 characters.
* Use periods consistently.

PR-URL: #13135
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michael Dawson <mhdawson@ibm.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
@aqrln aqrln deleted the improve-style-guide branch May 24, 2017 00:26
jasnell pushed a commit that referenced this pull request May 24, 2017
@aqrln @jasnell
doc: improve formatting of STYLE_GUIDE.md
c845869 
* Wrap text at 80 characters.
* Use periods consistently.

PR-URL: #13135
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michael Dawson <mhdawson@ibm.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
jasnell pushed a commit that referenced this pull request May 28, 2017
@aqrln @jasnell
doc: improve formatting of STYLE_GUIDE.md
3c91145 
* Wrap text at 80 characters.
* Use periods consistently.

PR-URL: #13135
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michael Dawson <mhdawson@ibm.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
@jasnell jasnell mentioned this pull request May 28, 2017
Closed
@gibfahn gibfahn mentioned this pull request Jun 15, 2017
Closed
3 tasks
MylesBorins pushed a commit that referenced this pull request Jul 17, 2017
@aqrln @MylesBorins
doc: improve formatting of STYLE_GUIDE.md
079b04e 
* Wrap text at 80 characters.
* Use periods consistently.

PR-URL: #13135
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Michael Dawson <mhdawson@ibm.com>
Reviewed-By: Gibson Fahnestock <gibfahn@gmail.com>
@MylesBorins MylesBorins mentioned this pull request Jul 18, 2017
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@refack refack refack approved these changes

@jasnell jasnell jasnell approved these changes

@Trott Trott Trott approved these changes

@lpinca lpinca lpinca approved these changes

@cjihrig cjihrig cjihrig approved these changes

@mhdawson mhdawson mhdawson approved these changes

@gibfahn gibfahn gibfahn approved these changes

Assignees
No one assigned
Labels
doc Issues and PRs related to the documentations.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.