doc,lib,test: capitalize comment sentences

[BridgeAR]

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

[nodejs-github-bot]

@BridgeAR build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/1914/pipeline

[Trott]

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]

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

[BridgeAR]

@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]

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]

+1 for the improved rule.

[BridgeAR]

Rebased due to conflicts.

Lite CI https://ci.nodejs.org/job/node-test-pull-request-lite-pipeline/1925/

[BridgeAR]

@nodejs/linting @nodejs/documentation PTAL

[Trott]

CI: https://ci.nodejs.org/job/node-test-pull-request/19560/ ✔️

[BridgeAR]

It would be great to get another review.

[BridgeAR]

Rebased due to conflicts.

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

[BridgeAR]

Landed in 50dd555