Frontend Comments Guidelines

Purpose of Comments

Improve code readability to enhance maintainability.

Considerations for Comments

Comments should eliminate confusion, not create it.
Comments are not a mere repetition of code.
Do not use comments to compensate for poor code; improve the code directly.
Unclear comments may indicate a lack of understanding of the code.
Comments need maintenance; keep them up to date. Poorly written or unmaintained comments can decrease code readability.

Good Comments

Include references to relevant documents or original code links.
When copying code, provide the link to the original file.
Explain the rationale behind the code. Code says "how," comments should explain "why."
Simplify complex code into one or two sentences; valuable comments help people quickly understand the code.

Examples of Bad Comments:

Thoughtless explanations: printf("%d\n", total_count++); /* Increment total count and print the old value */
Unused but retained code: Misuse of comments.
Incorrect comments: Comments not updated after code changes can mislead others.
Irrelevant comments.

Frontend Commenting Standards

1. Where to Add Comments

1. Public Code:

1.1 Constants, global variables, and public types: Must have comments.
1.2 File comments:

If a file contains multiple classes/functions, add a summary comment at the beginning of the file.
If a file contains only one exported class/function, add comments to that specific class/function.

1.3 Classes/Components:

Class: Add a comment above the class, summarizing its functionality.
Properties: All public properties must have comments.
Methods: Comments are required for all methods except for get/set methods and certain React lifecycle methods (willReceive, SCU).

1.4 Functions:

Exported functions must have comments; general functions are recommended to have comments.

2. Non-public Code:

2.1 Constants, global variables, and public types: Must have comments.
2.2 Business modules:
- Index files in directories should describe the overall structure and corresponding business.
2.3 Business components:
- Index files of components should describe their corresponding business significance.

3. Other (Regardless of Public or Non-public Code):

Tricky techniques, complex logic, sophisticated operations (mandatory).
Non-standard usages (mandatory).
Add comments to TODO, HACK (mandatory).
Share insights gained from extensive work (optional).
Document pitfalls to serve as a warning (optional).

2. Comment Formatting

1. File Headers

Used to explain the file's purpose; provide usage instructions and example code.

/**

 * Describe

 */

2. Classes

Used to explain the class's purpose; for complex utility classes, provide example code.

/**

 * Describe

 */

3. Global Variables

Used to explain the global variable's purpose.


/**

 * Describe

 */

4. Functions/Methods

Comments must include a function description, parameter explanations, and return value descriptions.


/**

 * Function description

 *

 * @param p1 Description of parameter 1

 * @param p2 Description of parameter 2, which may be lengthy

 *     Continue on a new line if necessary.

 * @param p3 Description of parameter 3 (optional)

 * @return Description of the return value

 */

function foo(p1, p2, p3) {

    var p3 = p3 || 10;

    return {

        p1: p1,

        p2: p2,

        p3: p3

    };

}

 

 

/**

 * For cases where parameter types are directly written in the function body, they can also be written in the type definition.

 *

 * @param  option Description of the parameter

 * @param  option.url Description of the option field

 * @param  option.method Description of the option field, optional parameter

 */

function foo(option) {

    // TODO

}

[Recommendation] When overriding parent class methods, use the @override tag. If the overridden method does not change in terms of parameter count, type, order, and return type, you can omit @param and @return tags, using only @override.

5. Constants

Used to explain the meaning of constants.


// Describe

6、Class Properties

Used to explain the meaning of class properties.


// Describe

7. Types

Used to explain the meaning of type definitions.

// Describe

8. Complex Logic, Sophisticated Operations; Non-standard Usages

// Describe

/**

 * Describe

 */

9、9. TODO, HACK, WARN

// TODO: Describe

/**

 * HACK: Describe

 */