preface

We write comments for other people to see, so that they can understand the code better and maintain the code better. This is also an aspect of high code quality.

At first glance, comments are easy to write, but comments don’t put everything together. Here are two principles for commenting:

  • As short As possible

In his book Clean Code, Robert C. Martin talks about this: comments are not necessary because the Code should be self-explanatory. If the code is not clear enough to require a comment, then perhaps it should be rewritten.

Note to avoid excessive overuse, do not note for the sake of note and note. Self-commenting code should be pursued, as the code itself allows the reader to make quick judgments.

// bad
// If the data is ready, do...
if (data && data.status === 'ready') {... }// good
const isDataReady = data && data.status === 'ready';
if (isDataReady) {
	...
}
Copy the code
  • Be As detailed As necessary.

Code can describe how, but it can’t explain why.

Comments should be as detailed as possible so that the reader can fully understand the logic and intent of the code.

Bad comments

  • Comments don’t help you read the code

In the example above, the code itself allows the reader to quickly determine that such comments should be deleted.

  • No comments for ongoing maintenance

Incorrect documentation can be worse than no documentation at all. There’s nothing more frustrating than seeing a comment that says something completely different than what the code below says. The only thing worse than wasting time is misleading.

One solution is to make sure that no matter what code you are updating, you also continue to maintain relevant comments. Of course, there will only be fewer and more meaningful comments, making maintenance easier.

  • Does not follow uniform style rules: single-line comment length, Spaces, blank lines, etc
// The bad comment is too long to read
/** * Convert an input value to a number for persistence.If the conversion fails, return original string. */
function toNumber (val) {... }// good
/** * Convert an input value to a number for persistence. * If the conversion fails, return original string. */
function toNumber (val) {... }Copy the code
  • Emotional comments: such as complaints, discrimination, funny and so on
/** * This project is very poor, there are many bugs, I left you a good workload, come on! * /
Copy the code

Good comment

  • why

We can write down the motivations, the intentions, the thoughts, the underlying logic.

/** * Convert an input value to a number for persistence. * If the conversion fails, return original string. */
function toNumber (val) {... }Copy the code
  • An explanation of a particular or difficult way of writing

Like a long RegExp. Can you understand how that works? Or could it be understood immediately a few years later?

/ / when and only when there is a "|" the number of times equal to 2, the content of "|" between bold and underlined
const reg = new RegExp("([^ \ \ |] *) (\ \ |) ([^ \ \ |] *) (\ \ |) ([^ \ \ |] *)"."ig");  
Copy the code

Also, there are always areas in our code that need to be improved, so here’s a special comment TODO to address this flaw. There are two kinds of special tags commonly used:

  1. // FIXME: What is the explanatory problem
  2. // TODO: describe what else TODO or the solution to the problem
  • What is clear to you may not be clear to others

In large teams, with junior engineers and even engineers from all types of backgrounds, people may not hesitate to tell you they need you to write notes, but many will thank you when you do.

  • Annotated like chapters in a book

Comment sections or snippets allow people to skip to the part that is most relevant to them. Even if the code is short, there may be a bit of long code snippets, and finding them quickly can be efficient.

  • File comment

We may also write fixed format comments at the head of the file, such as author, agreement, update date, etc.

  • Document class comments

Sometimes it is convention for apis, classes, functions, and so on to use document-class annotations.

How to write good comments

Annotation specifications

Note: this is a personal custom, for reference only.

  • Single-line comments

[Recommended] Declare variables after the declaration (too long or block specific can be placed above).

vm._vnode = null; // the root of the child tree
Copy the code

A blank line is required above the comment line (unless the comment line is above the top of a block) to increase readability:

// bad
// the root of the child tree
vm._vnode = null;
// v-once cached trees
vm._staticTrees = null;

// good
// the root of the child tree
vm._vnode = null;

// v-once cached trees
vm._staticTrees = null;

// good
A blank line is not required when the comment line is the top of a block
function setVNode(node) {  
  // the root of the child tree
  vm._vnode = node;
}

Copy the code
  • Multiline comment

[recommended] Multi-line comments using /**… */ instead of multiple lines //

// bad
// Convert an input value to a number for persistence.
// If the conversion fails, return original string.
function toNumber (val) {... }// good
/** * Convert an input value to a number for persistence. * If the conversion fails, return original string. */
function toNumber (val) {... }Copy the code
  • [Mandatory] There must be a space between the comment content and the comment character to improve readability. eslint:spaced-comment
// bad
//the root of the child tree
vm._vnode = null;

// good
// the root of the child tree
vm._vnode = null;

// bad
/** *Convert an input value to a number for persistence. *If the conversion fails, return original string. */
function toNumber (val) {... }// good
/** * Convert an input value to a number for persistence. * If the conversion fails, return original string. */
function toNumber (val) {... }Copy the code
  • Use documentation class annotations, such as functions, classes, files, events, and so on, using the JSDOC specification

Vs Code can be added automatically using the plug-in KorofileHeader and JSdoc.

/** * Set bridge information *@param {*} bridge* /
function setBridge(bridge) {
  this.bridge=bridge;
}
Copy the code

tool

Eslint

ESLint is the most popular JS code checking tool. ESLint has some rules for comments that you can optionally enable.

  • valid-jsdoc
  • require-jsdoc
  • no-warning-comments
  • capitalized-comments
  • line-comment-position
  • lines-around-comment
  • multiline-comment-style
  • no-inline-comments
  • spaced-comment

Sonar

Sonar is a code continuous integration platform that can statically scan code to get comment rate data for projects.

The comment rate reflects the proportion of comment lines in the total code line. Low comment rate is not good, but we should not blindly pursue high comment rate.

reference

  • The art of annotation
  • Commenting those things – Front-end Code Quality series (Part 1)
  • Write fried chicken in readable Code