spaced-comment

Обеспечивает единообразное расстояние после // или /* в комментарии

Некоторые руководства по стилю требуют или запрещают пробел непосредственно после начального // или /* комментария. Пробел после // или /* облегчает чтение текста в комментариях. С другой стороны, закомментировать код проще, если не нужно ставить пробел сразу после // или /*.

Подробное описание правила

Это правило обеспечивает единообразие пробелов после начала комментария // или /*. Кроме того, оно предоставляет несколько исключений для различных стилей документации.

Параметры

Правило принимает два параметра.

• Первый параметр — строка со значением "always" или "never". По умолчанию используется "always".

  • Если указано "always", после // или /* должен следовать как минимум один пробел.

  • Если указано "never", после них не должно быть пробелов.

• Правило также принимает второй параметр — объект с любыми из следующих ключей: "exceptions" и "markers".

  • Значение "exceptions" — это массив строковых шаблонов, которые считаются исключениями из правила. Правило не будет выдавать предупреждение, если шаблон находится в начале комментария и повторяется до конца строки или */, если комментарий однострочный. Обратите внимание, что исключения игнорируются, если первый аргумент — "never".

  "spaced-comment": ["error", "always", { "exceptions": ["-", "+"] }]
  

  • Значение "markers" — это массив строковых шаблонов, обозначающих маркеры для комментариев в стиле docblock, например дополнительный /, используемый для обозначения документации, обрабатываемой doxygen, vsdoc и другими инструментами, которым нужны дополнительные символы. Массив "markers" применяется независимо от значения первого аргумента, например "always" или "never".

  "spaced-comment": ["error", "always", { "markers": ["/"] }]
  

Разница между маркером и исключением состоит в том, что маркер встречается только в начале комментария, тогда как исключения могут находиться в любом месте строки комментария.

Также можно задать отдельные исключения и маркеры для блочных и строчных комментариев. Объект "block" может содержать дополнительный ключ "balanced" — логическое значение, указывающее, должны ли пробелы в начале и конце встроенных блочных комментариев быть сбалансированы. Значение по умолчанию — false.

• Если указаны "balanced": true и "always", после /* должен следовать как минимум один пробел, а перед */ должен находиться как минимум один пробел.

• Если указаны "balanced": true и "never", после /* и перед */ не должно быть пробелов.

• Если указано "balanced": false, наличие сбалансированных пробелов не проверяется.

"spaced-comment": ["error", "always", {
    "line": {
        "markers": ["/"],
        "exceptions": ["-", "+"]
    },
    "block": {
        "markers": ["!"],
        "exceptions": ["*"],
        "balanced": true
    }
}]

always

Примеры неправильного кода для этого правила с параметром "always":

/*eslint spaced-comment: ["error", "always"]*/

//This is a comment with no whitespace at the beginning

/*This is a comment with no whitespace at the beginning */

/* eslint spaced-comment: ["error", "always", { "block": { "balanced": true } }] */
/* This is a comment with whitespace at the beginning but not the end*/

Примеры правильного кода для этого правила с параметром "always":

/* eslint spaced-comment: ["error", "always"] */

// This is a comment with a whitespace at the beginning

/* This is a comment with a whitespace at the beginning */

/*
 * This is a comment with a whitespace at the beginning
 */

/*
This comment has a newline
*/

/* eslint spaced-comment: ["error", "always"] */

/**
* I am jsdoc
*/

never

Примеры неправильного кода для этого правила с параметром "never":

/*eslint spaced-comment: ["error", "never"]*/

// This is a comment with a whitespace at the beginning

/* This is a comment with a whitespace at the beginning */

/* \nThis is a comment with a whitespace at the beginning */

/*eslint spaced-comment: ["error", "never", { "block": { "balanced": true } }]*/
/*This is a comment with whitespace at the end */

Примеры правильного кода для этого правила с параметром "never":

/*eslint spaced-comment: ["error", "never"]*/

/*This is a comment with no whitespace at the beginning */

/*eslint spaced-comment: ["error", "never"]*/

/**
* I am jsdoc
*/

exceptions

Примеры неправильного кода для этого правила с параметром "always" в сочетании с "exceptions":

/* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["-"] } }] */

//--------------
// Comment block
//--------------

/* eslint spaced-comment: ["error", "always", { "exceptions": ["-", "+"] }] */

//------++++++++
// Comment block
//------++++++++

/* eslint spaced-comment: ["error", "always", { "exceptions": ["-", "+"] }] */

/*------++++++++*/
/* Comment block */
/*------++++++++*/

/* eslint spaced-comment: ["error", "always", { "line": { "exceptions": ["-+"] } }] */

/*-+-+-+-+-+-+-+*/
// Comment block
/*-+-+-+-+-+-+-+*/

/* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["*"] } }] */

/******** COMMENT *******/

Примеры правильного кода для этого правила с параметром "always" в сочетании с "exceptions":

/* eslint spaced-comment: ["error", "always", { "exceptions": ["-"] }] */

//--------------
// Comment block
//--------------

/* eslint spaced-comment: ["error", "always", { "line": { "exceptions": ["-"] } }] */

//--------------
// Comment block
//--------------

/* eslint spaced-comment: ["error", "always", { "exceptions": ["*"] }] */

/****************
 * Comment block
 ****************/

/* eslint spaced-comment: ["error", "always", { "exceptions": ["-+"] }] */

//-+-+-+-+-+-+-+
// Comment block
//-+-+-+-+-+-+-+

/*-+-+-+-+-+-+-+*/
// Comment block
/*-+-+-+-+-+-+-+*/

/* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["-+"] } }] */

/*-+-+-+-+-+-+-+*/
// Comment block
/*-+-+-+-+-+-+-+*/

/* eslint spaced-comment: ["error", "always", { "block": { "exceptions": ["*"] } }] */

/***************/

/********
COMMENT
*******/

markers

Примеры неправильного кода для этого правила с параметром "always" в сочетании с "markers":

/* eslint spaced-comment: ["error", "always", { "markers": ["/"] }] */

///This is a comment with a marker but without whitespace

/*eslint spaced-comment: ["error", "always", { "block": { "markers": ["!"], "balanced": true } }]*/
/*! This is a comment with a marker but without whitespace at the end*/

/*eslint spaced-comment: ["error", "never", { "block": { "markers": ["!"], "balanced": true } }]*/
/*!This is a comment with a marker but with whitespace at the end */

Примеры правильного кода для этого правила с параметром "always" в сочетании с "markers":

/* eslint spaced-comment: ["error", "always", { "markers": ["/"] }] */

/// This is a comment with a marker

/*eslint spaced-comment: ["error", "never", { "markers": ["!<"] }]*/

//!<This is a line comment with a marker

/*!<this is a block comment with a marker
subsequent lines are ignored
*/

/* eslint spaced-comment: ["error", "always", { "markers": ["global"] }] */

/*global ABC*/

Связанные правила

• spaced-line-comment

Версия

Это правило появилось в ESLint v0.23.0.

Ресурсы

• Исходный код правила
• Исходный код тестов