描述
I spend too much of my life "balancing" jsdoc and // comments so they're roughly the same length as each other. The consequences of doing this/not doing this are:
- [doing] precious time spent doing busywork
- [not doing] single line comments that are wider than most screens
- [not doing] comments that have weird line breaks and are less readable
- [doing] comments that don't get updated because they've already been meticulously aligned - so adding or deleting words would screw up the alignment
This is something humans are bad at and machines are good at. The rule could take the comment block, tokenize it and apply line breaks at the closest point to the target line length based on natural word breaks. The algorithm doesn't need to be complex. str.split(' ') is probably good enough for a first cut (/until there are complaints).
Of course this should be auto-fixable, otherwise it would be the worst thing ever.
Fail
/** a very very very very very very very very very very very very very very very very very very very very very very very very long comment */
foo();
// a short comment
// that should be on one line
foo();
Pass
/**
* a very very very very very very very very very very very very very very very
* very very very very very very very very very long comment
*/
foo();
// a short comment that should be on one line
foo();
Configuration
This rule should probably be fairly aggressive by default, but for the sake of adoption would need configuration:
type Config = {
maxLineLength: number; // default 80
allowShortSlashSlashComments: 'end-of-sentence' | 'never' | 'always' // default 'end-of-sentence'
}
// Error, comment lines too short:
/* eslint "unicorn/wrap-comments": ["error", {"allowShortSlashSlashComments": "never"] */
// foo!
// bar.
// baz?
// qux
foo();
// Ok, comment lines are short but separated by whitespace
// foo
// bar
foo();
// Ok, comment lines are short but end with sentence punctuation:
/* eslint "unicorn/wrap-comments": ["error", {"allowShortSlashSlashComments": "end-of-sentence"}] */
// foo!
// bar.
// baz?
// qux
foo();
I'd be happy to implement this rule but it's so generic that I think it belongs in a community library like this.
c.f. this prettier issue which is almost done with preschool: https://github.com/prettier/prettier/issues/265