eslint-plugin-comment-length v1.7.3

eslint-plugin-comment-length

This plugin provides ESLint rules that limit the line length of your comments. Furthermore, an automatic fix is included such that you can save time manually formatting your comments. As such it is recommended to apply this rule every time a file is saved in order to avoid the hassle of manually formatting comments.

This project aims to ease the process of writing long comments where each line needs to be cropped to a specific line length. This is similar to the max-len ESLint rule, but violations can be automatically fixed.

NB: There are several cases wherein the rules will not attempt to automatically format comments. This is to accomodate cases wherein it is not desired to break a comment into multiple lines. Examples include comments that:

• are not on their own lines.
• include eslint-[enable|disable]-*, stylelint-[enable|disable]-*, tslint:[enable|disable].
• consists of code snippets.
• are wrapped within backticks (e.g. `some-comment`)
• are part of JSDoc-like comments (i.e. starting with '@')

Specific cases will be expanded upon in the example sections below.

Installation

Yarn:

yarn add --dev eslint-plugin-comment-length

NPM:

npm i --save-dev eslint-plugin-comment-length

Usage

Add the following to your .eslintrc configuration:

{
  "extends": [
    "plugin:comment-length/recommended"
  ]
}

Rules

comment-length/limit-single-line-comments

Locates single-line commments, i.e. // comment, and ensures that each line never exceeds the configured length.

If a line violates this rule, the auto-fixer will attempt to combine logical groups of single-line comments and reformat those to ensure that each line is below the configured max length.

// this is one logical comment block. It will be automatically split into multiple lines if fixed. Especially if the content is very very very very very very long.
// This is the second line of the block.
// This is considered as a new block since the line above does not overflow.

// This line is also considered as a singular block.

Which will be transformed into:

// this is one logical comment block. It will be automatically split into
// multiple lines if fixed. Especially if the content is very very very very
// very very long. This is the second line of the block.
// This is considered as a new block since the line above does not overflow.

// This line is also considered as a singular block.

Options

{
  "comment-length/limit-single-line-comments": [
    "warn",
    {
      "maxLength": 80,
      "ignoreUrls": true
    }
  ]
}

Examples

Basic

// this is one logical comment block. It will be automatically split into multiple lines if fixed. Especially if the content is very very very very very very long.

Will be fixed into:

// this is one logical comment block. It will be automatically split into
// multiple lines if fixed. Especially if the content is very very very very
// very very long.

Indentation

When fixing this comment-block, then the leading whitespace on the following line will currently be discarded. This may change in the future.

As an example:

// When fixing this comment-block, then the leading whitespace on the following line will be discarded.
//    white-space will be discarded when fixing.

Will be fixed into:

// When fixing this comment-block, then the leading whitespace on the following
// line will be discarded. white-space will be discarded when fixing.

Must not be a comment with special semantics

The comments below will NOT be automatically fixable (as this will break functionality).

// eslint-disable-next-line comment-length/limit-single-line-comments, comment-length/limit-multi-line-comments
// styleline-disable-next-line some-css-plugin/some-css-rule, ...
// tslint:disable ...

Must be on own line

The comment below will NOT be automatically fixable (as it is not on its own line). This has been done as there is rarely much space available when a comment shares a line with actual code.

const myVariable = Math.max(0, Math.min(1, window.someValue)); // clamps the external value between 0 and 1.

Includes a comment within the comment

The comment below will NOT be automatically fixable as it includes a comment within itself.

The rationale behind this decision is that developers at times will have to out-comment snippets of code when debugging. When this happens comments may also be commented out (perhaps accidentally). In this case we would like to preserve the structure of the original comment, such that when it is commented back in it follows the original layout.

/** Here is my comment which // includes a very very long comment within itself. */

Includes a code snippet

The comment below will NOT be automatically fixable as it includes a comment within itself.

The rationaly is essentially the same as above. In particular we wish to avoid breaking lines when code is out-commented during debugging.

// const myVariableWhichDefinitelyOverflows = window.getComputedStyle(document.body).accentColor;

comment-length/limit-multi-line-comments

Locates multi-line comments, i.e. /* comment */ and ensures that each line in the comment never exceeds the configured length.

If a line violates this rule, the auto-fixer will attempt to combine logical groups of lines inside the comment and reformat those to ensure that each line is below the configured max length.

As an example the comment below, which combines several comments from the ESLint source code, is perfectly valid:

/*
 * NOTE: The CLI object should *not* call process.exit() directly. It should
 * only return exit codes. This allows other programs to use the CLI object and
 * still control when the program exits.
 * 
 * @property {("directive" | "problem" | "suggestion" | "layout")[]} [fixType] Specify the types of fixes to apply (directive, problem, suggestion, layout)
 * 
 * @example
 * ```tsx
 * const someValueAfterProcessing = process(value, (node) => ({
 *   ...node,
 *   newProp: 2, // @TODO, insert the correct value of newProp once available here. Do note that I overflow, but do not trigger an automatic fix.
 * }));
 * ```
 */

But the following would be considered as a violation:

/**
 * NOTE: The CLI object should *not* call process.exit() directly. It should only return exit codes. This allows other programs to use the CLI object and still control when the program exits.
 */

Which will be transformed into the snippet below when applying the automatic fix:

/*
 * NOTE: The CLI object should *not* call process.exit() directly. It should
 * only return exit codes. This allows other programs to use the CLI object and
 * still control when the program exits.
 */

Options

{
  "comment-length/limit-multi-line-comments": [
    "warn",
    {
      "maxLength": 80,
      "ignoreUrls": true
    }
  ]
}

Examples

Basic

/**
 * This is a single block.
 * This is another block which violates the maximum length. This block will as such be automatically fixed.
 * This is part of the previous block.
 * 
 * This is a third block.
 */

/**
 * This is a single block.
 * This is another block which violates the maximum length. This block will as
 * such be automatically fixed. This is part of the previous block.
 *
 * This is a third block.
 */

JSDoc

In order to preserve semantics of JSDoc-like comments the automatic fix will not apply to lines that seems to be part of a JSDoc comment (i.e. starting with the character "@").

At times, when JSDoc declarations (e.g. @example) span multiple lines, then it may be desired to combine with the backtick escape-hatch described below.

/**
 * @example Here is my JSDoc-comment which will not be automatically fixable in order to avoid altering semantics.
 */

Backticks

Backticks inside a multi-line comment acts as an escape hatch for the automatic fix. In other words, all content within backticks will never be considered as a block that can be automatically fixed.

/**
 * @example
 * ```ts
 * Everything within backticks will not be automatically formatted. They essientially acts as an escape-hatch for the automatic fix.
 * ```
 */

Indentation

When capturing logical blocks within a multi-line comment the rule will consider indentation levels. If two lines do not share the same indentation level, then they will never be considered as part of the same block.

This is illustrated with the following example:

/**
 * This is a single block which overflows the default maximum line-length (80 characters).
 *    Since this line has a different indentation level it will be considered as a separate block (which also overflows!)
 */

Will be fixed into:

/**
 * This is a single block which overflows the default maximum line-length (80
 * characters).
 *    Since this line has a different indentation level it will be considered
 *    as a separate block (which also overflows!)
 */

Single-line

/** In case a multi-line comment is on a single line and it violates the configured max-length, then it will be split into multiple lines automatically. */

Will be fixed into:

/**
 * In case a multi-line comment is on a single line and it violates the
 * configured max-length, then it will be split into multiple lines
 * automatically.
 */

Must not be a comment with special semantics

The comments below will NOT be automatically fixable (as this will break functionality).

/** eslint-disable comment-length/limit-single-line-comments, comment-length/limit-multi-line-comments */

Includes a comment within the comment

The comment below will NOT be automatically fixable as it includes a comment within itself.

The rationale behind this decision is that developers at times will have to out-comment snippets of code when debugging. When this happens comments may also be commented out (perhaps accidentally). In this case we would like to preserve the structure of the original comment, such that when it is commented back in it follows the original layout.

/** Here is my comment which // includes a very very long comment within itself. */

Includes a code snippet

The comment below will NOT be automatically fixable as it includes a comment within itself.

The rationaly is essentially the same as above. In particular we wish to avoid breaking lines when code is out-commented during debugging.

/** 
 * const myVariableWhichDefinitelyOverflows = window.getComputedStyle(document.body).accentColor;
 */