This article is a series of articles on front-end code specifications, which will cover all aspects of the front-end field. Other complete articles can be found on the homepage~

Code comments are an important part of software development. They help developers understand the function and purpose of the code, and are also the basis for code maintenance and team collaboration. A clear comment specification can improve the readability and maintainability of code. This article will introduce how to develop code comment specifications in front-end projects.

1. Types of comments

In front-end projects, we usually have two types of annotations:

• Single-line comments: Used to briefly describe or explain a single statement.
• Multi-line comments: used to describe complex logic or information about files and modules.

2. Single line comments

Single-line comments should follow the previous line of code or the end of the same line. Comments should be at least one space away from the code or previous line of comments.

//Correct single line comment 
const count = 1 ; //Initialize counter

// Wrong single line comment 
const count = 1 ; //Initialize counter

3. Multi-line comments

Multi-line comments are usually used in file headers to describe the function of the entire file, or to explain complex logic. Multi-line comments should have a clear beginning and end, with a space between the content and the asterisk.

/**
 * Correct multi-line comments
 * This is a function used to calculate the sum of an array
 * @param { number[] } numbers - the array of numbers to be calculated
 * @return { number } The sum of the array
 */ 
function  sum ( numbers ) {
   // ...
}

/* Wrong multi-line comment
This is a function for calculating the sum of an array
@param {number[]} numbers - the array of numbers to be calculated
@return {number} The sum of the array
*/ 
function  sum ( numbers ) {
   // ... 
}

4. JSDoc comments

JSDoc is a popular comment specification that not only improves the readability of code, but can also be used by some tools to generate documentation. In front-end projects, it is recommended to use JSDoc to annotate functions, classes and methods.

/**
 * Calculate the sum of arrays
 * @param { number[] } numbers - the array of numbers to be calculated
 * @returns { number } The sum of the array
 */ 
function  sum ( numbers ) {
   return numbers. reduce ( ( acc, current ) => acc + current, 0 );
}

5. Contents of comments

Comments should be clear, concise, and purposeful. Avoid meaningless comments or over-commenting. Comments should explain why, not what is being done. The code itself should be clear enough to express what it is doing.

// Correct comment 
// Because the user may enter a negative number, check before adding 
if (number < 0 ) {
   throw  new  Error ( 'Number must be positive' );
}

// Error comment 
// Check if the number is less than 0 
if (number < 0 ) {
   throw  new  Error ( 'Number must be positive' );
}

6. Update comments when code is modified

When code changes, related comments should be updated accordingly. Outdated comments can mislead other developers and make the code less readable.

7. Comment template

For some repetitive annotation content, such as components, modules, functions, etc., a unified annotation template can be developed.

/**
 * component name
 *
 * Describe the role and function of this component
 *
 * @prop { PropType } propName - description of prop
 */

8. Tool support

You can use some tools to enforce comment specifications, such as ESLint’s comment-related rules, or use Prettier to automatically format comments. This will be explained separately in a subsequent series of articles.

9. Avoid commenting entire blocks of code

Commented out code should not be kept in the code base. This code is often outdated and can cause confusion for other developers. If you need to retain historical versions of the code, you should use the version control system git to manage it.

// Error: commented out code 
// function oldCalculate() { 
// // ... 
// }

10. Special comment mark

Use special comment marks (such as TODO, FIXME, NOTE) in the code to identify areas that require special attention. These marks can help developers quickly locate the parts that require further work.

• TODO : Indicates functionality that needs to be added or completed in the future in the code. It is usually used to remind developers that there are features that are not yet implemented or require further work.
• FIXME : Indicates that there is a problem in the code and needs to be fixed. This usually means that the code is able to run, but the results may not be expected, or the code itself may be unstable.
• HACK : Refers to temporary solutions or inelegant code in the code. This is often used to fix a problem quickly, but a better solution may be needed in the long run.
• NOTE : Used to emphasize a particularly important piece of information in the code, such as explaining the logic of a complex algorithm or reminding why the code should be implemented in a specific way.
• OPTIMIZE : Hints that the performance of the code can be further optimized. This doesn’t necessarily indicate a problem with the code, but there may be opportunities for efficiency improvements.
• REVIEW : Indicates that the code requires additional review to determine if it meets the requirements or if there is a better way to implement it.
• DEPRECATED : Indicates that the code is obsolete and should not be used or will be removed in the future.
• NOCOMMIT : This is a warning that the code should not be committed to the version control system. This is often used for temporary changes during development, such as debugging code.

// TODO: Add exception handling 
function  loadData () {
   // ...
}

// FIXME: There is a problem with the algorithm implementation here, and 
function  calculate ( needs to be optimized in the future) {
   // ...
}

// NOTE: This is a temporary workaround 
function  temporaryFunction () {
   // ... 
}

Using these comment tags can help team members quickly identify specific parts of the code, but they should not be overused. Excessive TODOs or FIXMEs may indicate code quality issues, and these tags should be reviewed and addressed regularly.

11. Development tool notes

Development tools basically have convenient instructions to support comments. This article only lists the convenient methods or plug-ins for code comments in the two editors VSCode and WebStorm.

Add code comments in VSCode:

• Manual addition: Add line comments through shortcut keys Ctrl + /(Windows/Linux) or Cmd + /(Mac), and press the shortcut key after selecting the code. Annotations can also be written manually.
• Plug-ins: VSCode has many code comment-related plug-ins, such as Document This, jsdoc-comment, better-comments, vscode-todo-highlight, etc., which can be installed and used through the VSCode extension market to provide richer comment functions.

Add code comments in WebStorm:

• Automatically add: Enter above the function or method /**and press the Enter key, WebStorm will automatically generate a function comment template, and then you only need to fill in the corresponding information.
• Custom templates: Annotation templates can be customized in WebStorm’s settings to meet your team’s specific needs or follow specific annotation specifications.

Whether in VSCode or WebStorm, you can implement code comments through simple shortcut key operations or installing plug-ins, making the code more readable and maintainable.

Summarize

Good comment specifications can help improve code quality, promote team collaboration, and speed up new members’ familiarity with the project. They not only help themselves and others quickly understand the code, but also improve the maintainability of the code. In front-end projects, comments are not only for yourself, but also for other members of the team. Therefore, comments should be kept clear, accurate, and updated in a timely manner.

Through the comment specifications introduced in this article, I hope it can help you write clearer and more standardized comments in front-end projects.