Rule proposal: multiline-comment-style

[not-an-aardvark]

Please describe what the rule should do:

This rule enforces the styling of multiline comments. It has the following options:

• separate-lines disallows multiline block comments in favor of using consecutive line comments.
• starred-block (default) disallows consecutive line comments in favor of using a block comment, and requires block somments to have a * at the beginning of each line.
• bare-block disallows consecutive line comments in favor of using a block comment, and prohibits block comments from having a * at the beginning of each line.

The rule always ignores configuration comments (using the same heuristic as the other existing comment rules). When using the separate-lines or bare-block options, the rule ignores JSDoc comments.

What category of rule is this? (place an "X" next to just one item)

[x] Enforces code style
[ ] Warns about a potential error
[ ] Suggests an alternate way of doing something
[ ] Other (please specify:)

Provide 2-3 code examples that this rule will warn about:

/* eslint multiline-comment-style: [error, separate-lines] */

/* This line
calls foo() */
foo();

/*
 * This line
 * calls foo()
 */
foo();

/* eslint multiline-comment-style: [error, starred-block] */

// this line
// calls foo()
foo();

/* this line
calls foo() */
foo();

/* this comment
 * is missing a newline after /*
 */

/*
 * this comment
 * is missing a newline at the end */

/*
* the star in this line should have a space before it
 */

/*
 * the star on the following line should have a space before it
*/

/* eslint multiline-comment-style: [error, bare-block] */

// this line
// calls foo()
foo();

/*
 * this line
 * calls foo()
 */
foo();

Why should this rule be included in ESLint (instead of a plugin)?

Comment styling is an extremely common stylistic concern. Many styleguides require a particular format for multiline comments, including

• Airbnb styleguide
• Google styleguide
• JQuery styleguide

Since ESLint doesn't provide a rule to lint for comment style, it's difficult for project maintainers to automatically enforce a styleguide. Adding a rule for this would make it easier to use consistent formatting and to satisfy a very common styleguide requirement.

[JPeer264]

I could try to implement this, but I have absolutely no clue how to implement an autofixer for this. But I guess this can be also implemented later.

[not-an-aardvark]

I've already started working on an implementation for this. (Sorry, I should have mentioned that earlier.)

[melloc]

@not-an-aardvark Will this also enforce a space after * when using starred-block? (Or would that be better as an option to spaced-comment?)

[Nostradamos]

Any eta for this? Doesn't seem to be merged to master yet, but would be very nice to have.

[platinumazure]

Ping @not-an-aardvark, are you still working on this or can someone else take a crack at it?

[not-an-aardvark]

I'm not actively working on this right now, someone else can feel free to take it.

I have a WIP commit here, so feel free to work from my partial implementation and test cases.

I have a few minor usability concerns with the current design of the rule -- for example, it disallows "banner comments" like the one below, since they're just consecutive line comments:

//------------------------------
// this is a banner comment
//------------------------------

But maybe we can address those after the initial implementation.

[luxaritas]

What about use cases like this?

// Same line, "flat"
/* this line
calls foo() */

// Same line, lining up the text
/* this line
    calls foo() */

// Include newline, "flat"
/*
this line
calls foo()
*/

// Include newline, indented (to an arbitrary amount of spaces/tabs)
/*
    this line
    calls foo
*/

[not-an-aardvark]

@lfp6 could you clarify your question? I'm not sure what you're asking about with regard to those examples.