This article has participated in the “Digitalstar Project” and won a creative gift package to challenge the creative incentive money.

Tens of thousands of lines of code, comment the first line. Code is not standard, colleague tears two lines.

preface

Note I believe that partners are familiar, but it is this small note like project documents so many partners love and hate. Don’t like to write comments, and hate people don’t write comments. We’re going to talk about comments in JavaScript and CSS. Hopefully, this article will help you rediscover your love of comments and make coding fun.

A, grammar,

1.1 CSS comment

/* CSS comments */
Copy the code

1.2 JavaScript comments

// Single-line comment

/** ** * /** ** /** * * /
 
/* Of course, except the two ends of the * must be added, the other * is not also ok... * /
Copy the code

Two, basic use

2.1 Single-line comments

Typically, a single line of comment will appear directly above the code as a reminder:

/* The ability to comment CSS class names */

/* Top component */
.hd {
  position: fixed;
  width: 100vw;
}

Type area / * * /
.container {
  margin: 16px auto;
  width: 1200px;
}
Copy the code
// Note simple information with a single line comment

const userName = ""; / / user name
const userAvatar = ""; // User profile picture

/ / XXX function
const myFunction = () = > {};
Copy the code

2.2 Multi-line comments

Multi-line comments are used when there is too much information to comment on, and are often found near JavaScript functions. Let’s start with a question: why use multi-line comments, and isn’t single-line comments sweet? Let’s look at the following code:

/ / XXX function
const myFunction = ({ id, name, avatar, list, type }) = > {
  // Omit 30 lines of code here
};
Copy the code

Friends can see, one to five parameters, the internal function has only one short line number of lines of code comments, maybe you can remember this function when development purposes as well as the parameter type and whether it will spread, etc., but if you’re after a period of time before looking back at the code, then the brief comments could become your trouble. Not to mention no comments, no comments for a while cool, back to look at the code crematorium. The purpose of writing comments is to make your code more readable. By contrast, the following comments are much clearer:

/** * Adjusts the scroll distance * to display the given id element *@param    Id string ID of the mandatory element *@param    Distance number Non-mandatory distance from the top of the viewport (to avoid being obscured by the top fixed positioning element) *@returns  null* /
export const scrollToShowElement = (id = "", distance = 0) = > {
  return () = > {
    if(! id) {return;
    };

    const element = document.getElementById(id);
    if(! element) {return;
    };

    consttop = element? .offsetTop ||0;
    window.scroll(0, top - distance);
  };
};
Copy the code

For complex functions, a single line of comment is added to the function declaration in a uniform format, while a single line of comment is added to the internal complex logic and important variables, which complement each other. Multiline comments for function declarations are typically in the following format:

/** * function name * function introduction *@param    Parameter 1 Parameter 1 Data Type Mandatory 1 Description *@param    Parameter 2 Parameter 2 Data Type Mandatory 2 Description *@param    . *@returns  The return value * /
Copy the code

The advantage of multi-line comments is clarity, but the disadvantage is that they can be cumbersome (you can generate JavaScript function comment templates with the help of an editor). Single-line comments are recommended for functions with simple logic and multi-line comments for functions with complex logic and common/utility functions.

Of course, a good variable/function name can also reduce the reader’s cost of thinking, as can my article, Elegant Naming 🧊🧊.

Three, advanced use

As more code grows in both CSS and JavaScript, it becomes more and more difficult to find the code to change. So it is necessary to organize the code by module, with comments at the top of each module and empty lines at the end.

 /* The following code is only an example */

 /* Module 1 */
 /* Class name 1 */
 .class-a {}

 /* Class name 2 */
 .class-b {}

 /* Class name 3 */
 .class-c {}

 /* Module 2 */
 /* Class name 4 */
 .class-d {}

 /* Class name 5 */
 .class-e {}

 / *... * /
Copy the code
// The following code is only an example

/ / module 1
1 / / variables
const value1 = "";
2 / / variables
const value2 = "";
3 / / variables
const value3 = "";
1 / / function
const myFunction1 = () = > {};

/ / module 2
4 / / variables
const value4 = "";
/ / variable 5
const value5 = "";
6 / / variables
const value6 = "";
/ / function 2
const myFunction2 = () = > {};

// ...
Copy the code

There it is, but it doesn’t seem obvious, so let’s try adding – or = to the comment:

 / * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - module 1 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - * /
 /* Class name 1 */
 .class-a {}

 /* Class name 2 */
 .class-b {}

 /* Class name 3 */
 .class-c {}

 / * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- module 2 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - * /
 /* Class name 4 */
 .class-d {}

 /* Class name 5 */
 .class-e {}

 / *... * /
Copy the code
// The following code is only an example

/ * = = = = = = = = = = = = = = = = = = = = = = = = module 1 = = = = = = = = = = = = = = = = = = = = = = = = * /
1 / / variables
const value1 = "";
2 / / variables
const value2 = "";
3 / / variables
const value3 = "";
1 / / function
const myFunction1 = () = > {};

/ * = = = = = = = = = = = = = = = = = = = = = = = = module 2 = = = = = = = = = = = = = = = = = = = = = = = = * /
4 / / variables
const value4 = "";
/ / variable 5
const value5 = "";
6 / / variables
const value6 = "";
/ / function 2
const myFunction2 = () = > {};

// ...
Copy the code

It can be seen intuitively that the lengthened version of the annotation segmentation effect is better, higher differentiation. High-quality code often requires the most unpretentious comments to separate it. The JavaScript comment “splitter” suggests using multi-line comments.

“Gorgeous” dividing line:

 / * -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- gorgeous line -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - * /
 
/ * = = = = = = = = = = = = = = = = = = = = = = = = luxuriant line = = = = = = = = = = = = = = = = = = = = = = = = * /
Copy the code

Four, extension,

To do a good job, he must sharpen his tools. Here I would like to recommend a few VSCode editor plugins for comments.

4.1 Better Comments

You can change the color of your comments. There are four highlighted colors (red, orange, green, blue by default) and one black with strikeout. The color can be changed in the plugin configuration. Below is the example color and the use of the person in the project, one comment for each case.

Fancy coder must have plug-in, effectively improve annotation discrimination and beauty, from now on to love annotations. It only needs to add one or more characters to change the comment color, right out of the box.

/ /! Red highlight note, double slash after English exclamation mark! configuration
// Todo is highlighted in orange with the todo function followed by a double slash
// * green highlighted comment, double slash followed by * variable
/ /? Blue highlighted comments, double slash followed by question mark? component
// // black note with delete line, double slash followed by double slash //
Copy the code

4.2 koroFileHeader

Add-on: add notes to the header of the file, add function notes at the cursor, add one-key notes such as Buddha’s blessing never BUG, god and beast protection.

4.3 JavaScript Comment Snippet

Quick generation of JavaScript comments, rare but useful.

conclusion

I have to say that comments are really important in the coding process, and in order to write more elegant and maintainable code, we should also put the most important information in comments. A project’s readme. markdown and comments in the project are like project specifications, making it easier for non-project developers to read the meaning and ideas of the code. Let the code make us, let the code change the world, let the comments, with me!