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 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（默认）要求在块注释前空一行
• "afterBlockComment": true 要求在块注释后面留一个空行
• "beforeLineComment": true 在行注释前需要空行
• "afterLineComment": true 要求在行注释后空一行
• "allowBlockStart": true 允许注释出现在块语句、函数体、类、switch 语句和类静态块的开头
• "allowBlockEnd": true 允许注释放在块语句、函数体、类、switch 语句和类静态块的末尾
• "allowObjectStart": true 允许注释出现在对象字面量的开头
• "allowObjectEnd": true 允许在对象字面量的末尾出现注释
• "allowArrayStart": true 允许注释出现在数组字面量的开头
• "allowArrayEnd": true 允许在数组字面量的末尾出现注释
• "allowClassStart": true 允许注释出现在类的开头
• "allowClassEnd": true 允许注释出现在类的末尾
• "applyDefaultIgnorePatterns" 启用或禁用规则忽略默认注释模式
• "ignorePattern" 自定义模式将被规则忽略
• "afterHashbangComment": true 需要在哈希邦注释后留一个空行

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 中引入。

资源

• 规则源码
• 测试源码