Enforce empty lines around comments (lines-around-comment)
Many style guides require empty lines before or after comments. The primary goal of these rules is to make the comments easier to read and improve readability of the code.
Rule Details
This rule allows you to specify whether an empty line should be found
before or after a comment. It can be enabled separately for both block (/*
)
and line (//
) comments, and does not apply to comments that appear on the same
line as code.
By default an empty line is required above a block comment, such as in the following example:
var x = 0;
/**
* The vertical position.
*/
var y = 10;
The following would not pass the rule:
var x = 0;
/* the vertical position */
var y = 10;
Options
This rule has 6 options:
beforeBlockComment
(enabled by default)afterBlockComment
beforeLineComment
afterLineComment
allowBlockStart
allowBlockEnd
Any combination of these rules may be applied at the same time.
{
"lines-around-comment": [2, { "beforeBlockComment": true, "beforeLineComment": true }]
}
When set to false
the option is simply ignored.
Block Comments
Block comments are any comment that start with /*
and need not extend to multiple lines.
With both beforeBlockComment
and afterBlockComment
set to true
the following code
would not warn:
var night = "long";
/* what a great and wonderful day */
var day = "great"
This however would provide 2 warnings:
var night = "long";
/* what a great and wonderful day */
var day = "great"
With only beforeBlockComment
set to true
the following code
would not warn:
var night = "long";
/* what a great and wonderful day */
var day = "great"
But this would cause 1 warning:
var night = "long";
/* what a great and wonderful day */
var day = "great"
Line Comments
Line comments are any comments that start with //
.
With both beforeLineComment
and afterLineComment
set to true
the following code
would not warn:
var night = "long";
// what a great and wonderful day
var day = "great"
With only beforeLineComment
set to true
the following code
would not warn:
var night = "long";
// what a great and wonderful day
var day = "great"
Exceptions
allowBlockStart
option
When this option is set to true
, it allows the comment to be present at the start of any block statement without any space above it. This option can be useful when combined with options beforeLineComment
and beforeBlockComment
only.
With both beforeLineComment
and allowBlockStart
set to true
the following code
would not warn:
function foo(){
// what a great and wonderful day
var day = "great"
return day;
}
With both beforeBlockComment
and allowBlockStart
set to true
the following code
would not warn:
function foo(){
/* what a great and wonderful day */
var day = "great"
return day;
}
allowBlockEnd
option
When this option is set to true
, it allows the comment to be present at the end of any block statement without any space below it. This option can be useful when combined with options afterLineComment
and afterBlockComment
only.
With both afterLineComment
and allowBlockEnd
set to true
the following code
would not warn:
function foo(){
var day = "great"
return day;
// what a great and wonderful day
}
With both afterBlockComment
and allowBlockEnd
set to true
the following code
would not warn:
function foo(){
var day = "great"
return day;
/* what a great and wonderful day */
}
Inline comments
Inline comments are always excluded from the rule.
The following would be acceptable:
var x = 0;
var y = 10; /* the vertical position */
Empty lines are also not required at the beginning or end of a file.
When Not To Use It
Many people enjoy a terser code style and don’t mind comments bumping up against code. If you fall into that category this rule is not for you.
Related Rules
- space-before-blocks
- spaced-comment
- spaced-line-comment (deprecated)
Version
This rule was introduced in ESLint 0.22.0.