Skip to main content

Comments

eslint-plugin-complete contains several rules that make working with comments very strict. Why would anyone want to subject themselves to that?

Let's have a short discussion on the motivation for these rules.

The Types of Comments​

First, some jargon:

  • The // characters represent a "line" comment.
  • The /* characters represent a "block" comment. (It is ended with */.)
  • The /** characters represent a "JSDoc" comment. (It is also ended with */.)

Line Comments​

When line comments are on the same line as code, they are called trailing line comments. For example:

foo(); // hello world

When line comments are on their own line, they are called leading line comments. For example:

// hello world
foo();

Leading line comments can be either be single-line, or multi-line:

// This is a single-line line comment!

// This is a multi-line line comment! It's so long that
// it spills over on to the next line!

Block Comments​

Block comments are ignored by the rules of this plugin, since they are typically used to comment out blocks of code. For example:

/*
foo();
bar();
*/

JSDoc Comments​

JSDoc is a type of block comment that has a strictly defined format.

Like line comments, JSDoc comments can either be single-line or multi-line:

/** This is a single-line comment! */

/**
 * This is a multi-line line comment! It's so long that
 * it spills over on to the next line!
 */

Multi-line JSDoc comments use asterisks to denote the beginning of each line.

Ignoring In-Line Comments​

With the definitions out of the way, let's talk about how we use the different kinds of comments. It is common to use trailing line comments to write quick annotations:

foo(); // initialize the data
bar(); // probably not needed but just in case

In this circumstance, it would probably be a waste of time to force the programmer to write the comments in complete sentences, like this:

foo(); // We call this function to initialize the data.
bar(); // Calling this function is probably not needed, but we call it just in case.

Thus, trailing line comments are ignored by the rules in this plugin.

Annotating Information on Variables and Functions​

In contrast to trailing line comments, leading line comments are usually longer and more detailed. For example, say that we want to document something about the foo variable:

// matches the USS design document, section D
const foo = 100;

This is a good start. But the problem with annotating this information with a line comment is that it doesn't get "attached" to the variable. For example, in VSCode, if we hover over the foo variable (either at the declaration or elsewhere in the code), we would see that it has a value of 100, but we wouldn't see what the comment is.

To fix this problem, we can annotate the information as a JSDoc comment instead:

/** matches the USS design document, section D */
const foo = 100;

Now, wherever we happen to be in the code, we can always mouse over foo to see the comment. Nice! (And if we use a documentation generator like TypeDoc, it would automatically go in the generated documentation.)

However, one problem remains. You are supposed to use complete sentences in JSDoc comments, because it represents official information that will be extracted out and put on a documentation webpage. So we should update the comment to be like this:

/** Matches the USS design document, section D. */
const foo = 100;

Subsequently, it makes sense to have a linting rule to ensure that all JSDoc comments have complete sentences in them. This is the point of the complete/complete-sentences-jsdoc rule. (It is much smarter than the similar jsdoc/require-description-complete-sentence rule.)

Using a Ruler​

Many code projects have conventions to prevent lines from getting over a certain amount of characters. This kind of thing ensures that code is easy to read. It also is helpful to people with seeing disabilities, and for developers who prefer to open two files side by side.

In JavaScript/TypeScript, ESLint provides the max-len lint rule. This lint rule is often accompanied by an on-screen ruler inside of the IDE. Having the ruler on-screen is very nice, as it can accurately show when a line is over the limit. For example, to enable the ruler in VSCode:

{
  "editor.rulers": [100]
}

Formatters such as Prettier have taken this concept to the next level. Prettier automatically reformats your code to stay within the line limit. Since it happens automatically, using Prettier is a huge timer-saver!

Using JSDoc With a Ruler​

Code comments should stay to the left of the ruler for the exact same reasons that normal code should. Unfortunately, Prettier does not automatically reformat JSDoc comments. This makes working with them a real pain.

For example, say that you have the following JSDoc comment:

/**
 * But I must explain to you how all this mistaken idea of denouncing pleasure and praising pain was
 * born and I will give you a complete account of the system, and expound the actual teachings of
 * the great explorer of the truth, the master-builder of human happiness. No one rejects, dislikes,
 * or avoids pleasure itself, because it is pleasure, but because those who do not know how to
 * pursue pleasure rationally encounter consequences that are extremely painful.
 */

This comment is aligned with a ruler of 100 characters. Imagine that I need to add some new information before the "No one rejects" sentence:

/**
 * But I must explain to you how all this mistaken idea of denouncing pleasure and praising pain was
 * born and I will give you a complete account of the system, and expound the actual teachings of
 * the great explorer of the truth, the master-builder of human happiness. ADDING SOME INFORMATION HERE. No one rejects, dislikes,
 * or avoids pleasure itself, because it is pleasure, but because those who do not know how to
 * pursue pleasure rationally encounter consequences that are extremely painful.
 */

Oh no! Now we have to manually re-adjust the next N lines of the block in order to keep everything aligned.

This annoying problem is why the complete/format-jsdoc-comments rule exists. After adding the "ADDING SOME INFORMATION HERE", all we have to do is save the file, and all of the subsequent lines will be automatically adjusted.

Using Line Comments With a Ruler​

The same problem happens with multi-line leading line comments:

// But I must explain to you how all this mistaken idea of denouncing pleasure and praising pain was
// born and I will give you a complete account of the system, and expound the actual teachings of
// the great explorer of the truth, the master-builder of human happiness. ADDING SOME INFORMATION HERE. No one rejects, dislikes,
// or avoids pleasure itself, because it is pleasure, but because those who do not know how to
// pursue pleasure rationally encounter consequences that are extremely painful.

After adding "ADDING INFORMATION HERE", we have to manually re-adjust the next N lines of the block in order to keep everything aligned.

Similar to the format-jsdoc-comments rule, the complete/format-line-comments rule saves us from the tedium of manually formatting.

Consistency With Line Comments and JSDoc Comments​

You might notice that in general, there is a bit of asymmetry between JSDoc comments and leading line comments.

Specifically, you might already know that you are supposed to use complete sentences for JSDoc comments. But you might not use complete sentences for your leading line comments. For example:

// This is how we do things here
// I don't know why
// It's just the way it is

In this style, line breaks are used instead of periods. This kind of style can look nice under certain circumstances. But once we are committed to using the format-line-comments rule, this style becomes an anti-pattern, because the rule will change it to this:

// This is how we do things here I don't know why It's just the way it is

In order to prevent this from happening, the complete/complete-sentences-line-comments rule forces you to use complete sentences for any leading line comment. In the previous example, once we use complete sentences, it gets auto-formatted to this:

// This is how we do things here. I don't know why. It's just the way it is.

Much better!

Even if you don't use the format-line-comments rule, having consistency between JSDoc comments and line comments is a good thing. Why should JSDoc comments be styled one way (with complete sentences) and leading line comments styled another way (without complete sentences)? Having a mismatch here is distracting for someone reading the code, and confusing for someone trying to work on the code: "Am I supposed to use punctuation here or not?" Better to make things always consistent.

Finally, note that complete-sentences are not enforced for certain kinds of single-line leading line comments. For example, the rule allows you to make quick annotations like this:

// Local variables
let a;
let b;
let c;

// Constants
const foo = 123;
const bar = 456;

All of the rules in this plugin are designed to try and be as smart as possible. They are trying to hit the sweet spot between false positives and false negatives. You can open a GitHub issue if you find a situation where this rule should be smarter.