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.

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

doc,lib,test: capitalize comment sentences #24996

Closed
wants to merge 1 commit into
base: master
from

Conversation

@BridgeAR
Copy link
Member

BridgeAR commented Dec 12, 2018

This expands the eslint capitalize comment rule to be active for comments
above 50 characters (instead of 62) and ignores starting words which contain # or [.

Checklist
  • make -j4 test (UNIX), or vcbuild test (Windows) passes
  • tests and/or benchmarks are included
  • documentation is changed or added
  • commit message follows commit guidelines
@Trott

This comment has been minimized.

Copy link
Member

Trott commented Dec 12, 2018

Not an objection, but an observation/concern: I'm not sure how I feel about codifying the backticks-to-surround-code in comments. That's a markdown typography convention, not a widely-understood convention for plain-text comments. (We understand it because we're editing markdown all the time.)

@Trott

This comment has been minimized.

Copy link
Member

Trott commented Dec 12, 2018

With all this churn, and the brittle magic number for line length to ignore, I wonder if what we really should do is stop leaving nits for capitalizing comments. Make peace with the fact that some comments will be capitalized and others won't. This does not significantly improve our code.

Still not feeling an objection, but wondering if that's where I'm headed and curious if others feel the same or not....

Show resolved Hide resolved benchmark/_benchmark_progress.js Outdated
Show resolved Hide resolved benchmark/net/tcp-raw-c2s.js Outdated
Show resolved Hide resolved benchmark/net/tcp-raw-s2c.js Outdated
@BridgeAR

This comment has been minimized.

Copy link
Member

BridgeAR commented Dec 13, 2018

@Trott

I'm not sure how I feel about codifying the backticks-to-surround-code in comments

We use a lot of markdown and having them as code comments should be natural for anyone working on the source. Having them in the docs might be less ideal. Do you have a good alternative at hand?

The brittle magic number for line length to ignore

I was not sure if it's to early to open this PR or not but I would like to reduce that magic number from time to time (each couple minor releases) so that at some point we don't have a character limit at all. It was just a way to limit the churn a bit.

I wonder if what we really should do is stop leaving nits for capitalizing comments. [...] This does not significantly improve our code.

While I agree that it's not a huge improvement, it's just a one time task as most of our small improvements. As soon as the rule is fully introduces we do not have to worry about any of it again :) Since we are human, it's difficult to stop leaving the nits for such things.

@Trott

This comment has been minimized.

Copy link
Member

Trott commented Dec 13, 2018

Do you have a good alternative at hand?

@BridgeAR No. I think I'm OK with it. It's not ideal IMO but I also don't have a better idea, so I shouldn't block progress. If I ever think of a better idea, I can open a PR changing it to something else. :-D

I was not sure if it's to early to open this PR or not but I would like to reduce that magic number from time to time

Worth a shot! Thanks for explaining that.

Since we are human, it's difficult to stop leaving the nits for such things.

I certainly can't dispute that. Very true.

@ryzokuken
Copy link
Member

ryzokuken left a comment

+1 for the improved rule.

@BridgeAR BridgeAR force-pushed the BridgeAR:more-eslint-stuff branch from e919311 to 6874daf Dec 13, 2018

@BridgeAR

This comment has been minimized.

Copy link
Member

BridgeAR commented Dec 13, 2018

@BridgeAR

This comment has been minimized.

Copy link
Member

BridgeAR commented Dec 14, 2018

@Trott

This comment has been minimized.

Copy link
Member

Trott commented Dec 15, 2018

@BridgeAR

This comment has been minimized.

Copy link
Member

BridgeAR commented Dec 17, 2018

It would be great to get another review.

doc,lib,test: capitalize comment sentences
This activates the eslint capitalize comment rule for comments
above 50 characters.

@BridgeAR BridgeAR force-pushed the BridgeAR:more-eslint-stuff branch from 6874daf to eccc1db Dec 17, 2018

@BridgeAR

This comment has been minimized.

Copy link
Member

BridgeAR commented Dec 17, 2018

Rebased due to conflicts.

CI before landing: https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/1980/

BridgeAR added a commit to BridgeAR/node that referenced this pull request Dec 17, 2018

doc,lib,test: capitalize comment sentences
This activates the eslint capitalize comment rule for comments
above 50 characters.

PR-URL: nodejs#24996
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
@BridgeAR

This comment has been minimized.

Copy link
Member

BridgeAR commented Dec 17, 2018

Landed in 50dd555

@BridgeAR BridgeAR closed this Dec 17, 2018

MylesBorins added a commit that referenced this pull request Dec 25, 2018

doc,lib,test: capitalize comment sentences
This activates the eslint capitalize comment rule for comments
above 50 characters.

PR-URL: #24996
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

@MylesBorins MylesBorins referenced this pull request Dec 25, 2018

Merged

v11.6.0 proposal #25175

refack added a commit to refack/node that referenced this pull request Jan 14, 2019

doc,lib,test: capitalize comment sentences
This activates the eslint capitalize comment rule for comments
above 50 characters.

PR-URL: nodejs#24996
Reviewed-By: Ujjwal Sharma <usharma1998@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Sakthipriyan Vairamani <thechargingvolcano@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment