Rule proposal: `wrap-comments`

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

[sindresorhus]

Why not just use soft-wrapping? Meaning, let the editor handle the wrapping. I honestly never understood why people prefer hard-wrapping. It’s just a lot of manual work that has to happen every time there are changes.

[mmkal]

Tried it. I’ve got a basic rule working, which is good for simple cases, but on trying it out on this repo and my team’s at work, I hadn’t thought of temporarily-commented-out code, weird markdown in jsdoc, as well as many different way that humans organically use conventions to break lines, e.g. with capitals

// This is a line
// This is another line

Or format things very deliberately:

// foo bar
//     ^^ pointing at bar

So I’m putting this on hold for now. If anyone feels like trying this out, let me know and I can share what I have so far. In the meantime I’ll try to think of a good heuristic for determining “this is a paragraph of prose and it’s safe to fiddle with the line breaks” vs “not sure what this, I’m going to leave it alone” that is simple and doesn’t involve writing a general natural language parser.