lines-around-comment

注释周围需要空行

此规则在 ESLint v8.53.0 中已弃用。请在 @stylistic/eslint-plugin-js 中使用 相应的规则。

¥This rule was deprecated in ESLint v8.53.0. Please use the corresponding rule in @stylistic/eslint-plugin-js.

许多风格指南要求在注释之前或之后有空行。这些规则的主要目标是使注释更易于阅读并提高代码的可读性。

¥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 requires empty lines before and/or after comments. It can be enabled separately for both block (/*) and line (//) comments. This rule does not apply to comments that appear on the same line as code and does not require empty lines at the beginning or end of a file.

选项

¥Options

此规则有一个对象选项：

¥This rule has an object option:

• "beforeBlockComment": true（默认）在块注释之前需要一个空行

  ¥"beforeBlockComment": true (default) requires an empty line before block comments

• "afterBlockComment": true 需要在块注释后有一个空行

  ¥"afterBlockComment": true requires an empty line after block comments

• "beforeLineComment": true 需要在行注释前有一个空行

  ¥"beforeLineComment": true requires an empty line before line comments

• "afterLineComment": true 需要在行注释后有一个空行

  ¥"afterLineComment": true requires an empty line after line comments

• "allowBlockStart": true 允许注释出现在块语句、函数体、类、switch 语句和类静态块的开头

  ¥"allowBlockStart": true allows comments to appear at the start of block statements, function bodies, classes, switch statements, and class static blocks

• "allowBlockEnd": true 允许注释出现在块语句、函数体、类、switch 语句和类静态块的末尾

  ¥"allowBlockEnd": true allows comments to appear at the end of block statements, function bodies, classes, switch statements, and class static blocks

• "allowObjectStart": true 允许注释出现在对象字面量的开头

  ¥"allowObjectStart": true allows comments to appear at the start of object literals

• "allowObjectEnd": true 允许注释出现在对象字面量的末尾

  ¥"allowObjectEnd": true allows comments to appear at the end of object literals

• "allowArrayStart": true 允许注释出现在数组字面量的开头

  ¥"allowArrayStart": true allows comments to appear at the start of array literals

• "allowArrayEnd": true 允许注释出现在数组字面量的末尾

  ¥"allowArrayEnd": true allows comments to appear at the end of array literals

• "allowClassStart": true 允许注释出现在类开始时

  ¥"allowClassStart": true allows comments to appear at the start of classes

• "allowClassEnd": true 允许注释出现在类结束时

  ¥"allowClassEnd": true allows comments to appear at the end of classes

• "applyDefaultIgnorePatterns" 启用或禁用规则忽略的默认注释模式

  ¥"applyDefaultIgnorePatterns" enables or disables the default comment patterns to be ignored by the rule

• 规则将忽略 "ignorePattern" 个自定义模式

  ¥"ignorePattern" custom patterns to be ignored by the rule

• "afterHashbangComment": true 需要在 hashbang 注释后有一个空行

  ¥"afterHashbangComment": true requires an empty line after hashbang comments

beforeBlockComment

使用默认 { "beforeBlockComment": true } 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the default { "beforeBlockComment": true } option:

/*eslint lines-around-comment: ["error", { "beforeBlockComment": true }]*/

var night = "long";
/* what a great and wonderful day */
var day = "great"
1
2
3
4
5

使用默认 { "beforeBlockComment": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the default { "beforeBlockComment": true } option:

/*eslint lines-around-comment: ["error", { "beforeBlockComment": true }]*/

var night = "long";

/* what a great and wonderful day */
var day = "great"
1
2
3
4
5
6

afterBlockComment

使用 { "afterBlockComment": true } 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the { "afterBlockComment": true } option:

/*eslint lines-around-comment: ["error", { "afterBlockComment": true }]*/

var night = "long";

/* what a great and wonderful day */
var day = "great"
1
2
3
4
5
6

使用 { "afterBlockComment": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterBlockComment": true } option:

/*eslint lines-around-comment: ["error", { "afterBlockComment": true }]*/

var night = "long";

/* what a great and wonderful day */

var day = "great"
1
2
3
4
5
6
7

beforeLineComment

使用 { "beforeLineComment": true } 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the { "beforeLineComment": true } option:

/*eslint lines-around-comment: ["error", { "beforeLineComment": true }]*/

var night = "long";
// what a great and wonderful day
var day = "great"
1
2
3
4
5

使用 { "beforeLineComment": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeLineComment": true } option:

/*eslint lines-around-comment: ["error", { "beforeLineComment": true }]*/

var night = "long";

// what a great and wonderful day
var day = "great"
1
2
3
4
5
6

afterLineComment

使用 { "afterLineComment": true } 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the { "afterLineComment": true } option:

/*eslint lines-around-comment: ["error", { "afterLineComment": true }]*/

var night = "long";
// what a great and wonderful day
var day = "great"
1
2
3
4
5

使用 { "afterLineComment": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterLineComment": true } option:

/*eslint lines-around-comment: ["error", { "afterLineComment": true }]*/

var night = "long";
// what a great and wonderful day

var day = "great"
1
2
3
4
5
6

allowBlockStart

使用 { "beforeLineComment": true, "allowBlockStart": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeLineComment": true, "allowBlockStart": true } options:

/*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowBlockStart": true }]*/

function foo(){
    // what a great and wonderful day
    var day = "great"
    return day;
}

if (bar) {
    // what a great and wonderful day
    foo();
}

class C {
    // what a great and wonderful day

    method() {
        // what a great and wonderful day
        foo();
    }

    static {
        // what a great and wonderful day
        foo();
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

使用 { "beforeBlockComment": true, "allowBlockStart": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeBlockComment": true, "allowBlockStart": true } options:

/*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowBlockStart": true }]*/

function foo(){
    /* what a great and wonderful day */
    var day = "great"
    return day;
}

if (bar) {
    /* what a great and wonderful day */
    foo();
}

class C {
    /* what a great and wonderful day */

    method() {
        /* what a great and wonderful day */
        foo();
    }

    static {
        /* what a great and wonderful day */
        foo();
    }
}

switch (foo) {
  /* what a great and wonderful day */

  case 1:
    bar();
    break;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

allowBlockEnd

使用 { "afterLineComment": true, "allowBlockEnd": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterLineComment": true, "allowBlockEnd": true } option:

/*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowBlockEnd": true }]*/

function foo(){
    var day = "great"
    return day;
    // what a great and wonderful day
}

if (bar) {
    foo();
    // what a great and wonderful day
}

class C {

    method() {
        foo();
        // what a great and wonderful day
    }

    static {
        foo();
        // what a great and wonderful day
    }

    // what a great and wonderful day
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

使用 { "afterBlockComment": true, "allowBlockEnd": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterBlockComment": true, "allowBlockEnd": true } option:

/*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowBlockEnd": true }]*/

function foo(){
    var day = "great"
    return day;

    /* what a great and wonderful day */
}

if (bar) {
    foo();

    /* what a great and wonderful day */
}

class C {

    method() {
        foo();

        /* what a great and wonderful day */
    }

    static {
        foo();

        /* what a great and wonderful day */
    }

    /* what a great and wonderful day */
}

switch (foo) {
  case 1:
    bar();
    break;

  /* what a great and wonderful day */
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

allowClassStart

使用 { "beforeLineComment": true, "allowClassStart": false } 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the { "beforeLineComment": true, "allowClassStart": false } option:

/*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowClassStart": false }]*/

class foo {
    // what a great and wonderful day
    day() {}
};
1
2
3
4
5
6

使用 { "beforeLineComment": true, "allowClassStart": false } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeLineComment": true, "allowClassStart": false } option:

/*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowClassStart": false }]*/

class foo {

    // what a great and wonderful day
    day() {}
};
1
2
3
4
5
6
7

使用 { "beforeLineComment": true, "allowClassStart": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeLineComment": true, "allowClassStart": true } option:

/*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowClassStart": true }]*/

class foo {
    // what a great and wonderful day
    day() {}
};
1
2
3
4
5
6

使用 { "beforeBlockComment": true, "allowClassStart": false } 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the { "beforeBlockComment": true, "allowClassStart": false } option:

/*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowClassStart": false }]*/

class foo {
    /* what a great and wonderful day */
    day() {}
};
1
2
3
4
5
6

使用 { "beforeBlockComment": true, "allowClassStart": false } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeBlockComment": true, "allowClassStart": false } option:

/*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowClassStart": false }]*/

class foo {

    /* what a great and wonderful day */
    day() {}
};
1
2
3
4
5
6
7

使用 { "beforeBlockComment": true, "allowClassStart": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeBlockComment": true, "allowClassStart": true } option:

/*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowClassStart": true }]*/

class foo {
    /* what a great and wonderful day */
    day() {}
};
1
2
3
4
5
6

allowClassEnd

使用 { "afterLineComment": true, "allowClassEnd": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterLineComment": true, "allowClassEnd": true } option:

/*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowClassEnd": true }]*/

class foo {
    day() {}
    // what a great and wonderful day
};
1
2
3
4
5
6

使用 { "afterBlockComment": true, "allowClassEnd": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterBlockComment": true, "allowClassEnd": true } option:

/*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowClassEnd": true }]*/

class foo {
    day() {}

    /* what a great and wonderful day */
};
1
2
3
4
5
6
7

allowObjectStart

使用 { "beforeLineComment": true, "allowObjectStart": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeLineComment": true, "allowObjectStart": true } option:

/*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowObjectStart": true }]*/

var foo = {
    // what a great and wonderful day
    day: "great"
};

const {
    // what a great and wonderful day
    foo: someDay
} = {foo: "great"};

const {
    // what a great and wonderful day
    day
} = {day: "great"};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

使用 { "beforeBlockComment": true, "allowObjectStart": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeBlockComment": true, "allowObjectStart": true } option:

/*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowObjectStart": true }]*/

var foo = {
    /* what a great and wonderful day */
    day: "great"
};

const {
    /* what a great and wonderful day */
    foo: someDay
} = {foo: "great"};

const {
    /* what a great and wonderful day */
    day
} = {day: "great"};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

allowObjectEnd

使用 { "afterLineComment": true, "allowObjectEnd": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterLineComment": true, "allowObjectEnd": true } option:

/*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowObjectEnd": true }]*/

var foo = {
    day: "great"
    // what a great and wonderful day
};

const {
    foo: someDay
    // what a great and wonderful day
} = {foo: "great"};

const {
    day
    // what a great and wonderful day
} = {day: "great"};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

使用 { "afterBlockComment": true, "allowObjectEnd": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterBlockComment": true, "allowObjectEnd": true } option:

/*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowObjectEnd": true }]*/

var foo = {
    day: "great"

    /* what a great and wonderful day */
};

const {
    foo: someDay

    /* what a great and wonderful day */
} = {foo: "great"};

const {
    day

    /* what a great and wonderful day */
} = {day: "great"};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

allowArrayStart

使用 { "beforeLineComment": true, "allowArrayStart": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeLineComment": true, "allowArrayStart": true } option:

/*eslint lines-around-comment: ["error", { "beforeLineComment": true, "allowArrayStart": true }]*/

var day = [
    // what a great and wonderful day
    "great",
    "wonderful"
];

const [
    // what a great and wonderful day
    someDay
] = ["great", "not great"];
1
2
3
4
5
6
7
8
9
10
11
12

使用 { "beforeBlockComment": true, "allowArrayStart": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "beforeBlockComment": true, "allowArrayStart": true } option:

/*eslint lines-around-comment: ["error", { "beforeBlockComment": true, "allowArrayStart": true }]*/

var day = [
    /* what a great and wonderful day */
    "great",
    "wonderful"
];

const [
    /* what a great and wonderful day */
    someDay
] = ["great", "not great"];
1
2
3
4
5
6
7
8
9
10
11
12

allowArrayEnd

使用 { "afterLineComment": true, "allowArrayEnd": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterLineComment": true, "allowArrayEnd": true } option:

/*eslint lines-around-comment: ["error", { "afterLineComment": true, "allowArrayEnd": true }]*/

var day = [
    "great",
    "wonderful"
    // what a great and wonderful day
];

const [
    someDay
    // what a great and wonderful day
] = ["great", "not great"];
1
2
3
4
5
6
7
8
9
10
11
12

使用 { "afterBlockComment": true, "allowArrayEnd": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterBlockComment": true, "allowArrayEnd": true } option:

/*eslint lines-around-comment: ["error", { "afterBlockComment": true, "allowArrayEnd": true }]*/

var day = [
    "great",
    "wonderful"

    /* what a great and wonderful day */
];

const [
    someDay

    /* what a great and wonderful day */
] = ["great", "not great"];
1
2
3
4
5
6
7
8
9
10
11
12
13
14

ignorePattern

默认情况下，此规则会忽略以以下单词开头的注释：eslint, jshint, jslint, istanbul, global, exported, jscs.

¥By default this rule ignores comments starting with the following words: eslint, jshint, jslint, istanbul, global, exported, jscs.

此规则的正确代码示例：

¥Examples of correct code for this rule:

/*eslint lines-around-comment: ["error"]*/

foo();
/* jshint mentioned in this comment */
bar();
1
2
3
4
5

要忽略默认值之外的更多注释，请将 ignorePattern 选项设置为将传递给 RegExp 构造函数 的字符串模式。

¥To ignore more comments in addition to the defaults, set the ignorePattern option to a string pattern that will be passed to the RegExp constructor.

ignorePattern 选项的正确代码示例：

¥Examples of correct code for the ignorePattern option:

/*eslint lines-around-comment: ["error", { "ignorePattern": "pragma" }] */

foo();
/* jshint mentioned in this comment */
bar();

foo();
/* a valid comment using pragma in it */
1
2
3
4
5
6
7
8

ignorePattern 选项的错误代码示例：

¥Examples of incorrect code for the ignorePattern option:

/*eslint lines-around-comment: ["error", { "ignorePattern": "pragma" }] */

1 + 1;
/* something else */
1
2
3
4

applyDefaultIgnorePatterns

即使提供了 ignorePattern，也会应用默认忽略模式。如果要省略默认模式，请将此选项设置为 false。

¥Default ignore patterns are applied even when ignorePattern is provided. If you want to omit default patterns, set this option to false.

{ "applyDefaultIgnorePatterns": false } 选项的正确代码示例：

¥Examples of correct code for the { "applyDefaultIgnorePatterns": false } option:

/*eslint lines-around-comment: ["error", { "ignorePattern": "pragma", applyDefaultIgnorePatterns: false }] */

foo();
/* a valid comment using pragma in it */
1
2
3
4

{ "applyDefaultIgnorePatterns": false } 选项的错误代码示例：

¥Examples of incorrect code for the { "applyDefaultIgnorePatterns": false } option:

/*eslint lines-around-comment: ["error", { "applyDefaultIgnorePatterns": false }] */

foo();
/* jshint mentioned in comment */

1
2
3
4
5

afterHashbangComment

使用 { "afterHashbangComment": true } 选项的此规则的错误代码示例：

¥Examples of incorrect code for this rule with the { "afterHashbangComment": true } option:

#!foo
var day = "great"

/*eslint lines-around-comment: ["error", { "afterHashbangComment": true }] */
1
2
3
4

使用 { "afterHashbangComment": true } 选项的此规则的正确代码示例：

¥Examples of correct code for this rule with the { "afterHashbangComment": true } option:

#!foo

var day = "great"

/*eslint lines-around-comment: ["error", { "afterHashbangComment": true }] */
1
2
3
4
5

何时不使用

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

相关规则

• space-before-blocks
• spaced-comment

版本

此规则是在 ESLint v0.22.0 中引入。

资源

• 规则源码
• 测试源码