Preface:
Good comments improve code quality by making it more readable and maintainable. So what is a good comment? How to write good comments? Good comments improve code quality by making it more readable and maintainable.
So what is a good comment? How to write good comments? This article will discuss JS annotation from the purpose and principle of annotation.
I. Purpose and principles of annotations
Purpose of comments: Improve code readability, and therefore code maintainability “Don’t annotate As long As necessary” means to avoid making too many or too many comments. Don’t annotate for the sake of annotating. Redundant comments are equivalent to redundant code, and in addition to contributing to readability, changing comments can be a burden if the code needs to be changed.
We should go for “self-commenting code”, where the code itself is highly readable (through clear naming, reasonable structure, etc.). Here’s an example:
If (data.success && data.result.length > 0) {renderTable(data); } // good const isTableDataReady = data.success && data.result.length > 0; if (isTableDataReady) { renderTable(data); } “as detailed as necessary” means that comments should be written in as much detail as possible so that the reader can fully understand the logic and intent of the code.
What is a good comment and what is a bad comment
According to the principles of comments, we should judge whether a comment is “necessary” based on whether it helps the reader read and understand the code better.
Good comments include:
To help readers better understand the code logic and structure, for example:
init: function() {
Const config = getConfig();
Const userInfo = getUserInfo();
// Initialize doInit(config, userInfo) according to the configuration and user information;
// If there is special logic for custom configuration
if (config.custom) { … }}
A special or difficult-to-understand explanation, such as /**
- parseInt was the reason my code was slow.
- Bitshifting the String to coerce it to a
- Number made it a lot faster. */
const val = inputValue >> 0;
Special tag comments: tags that have special meanings, such as TODO, FIXME, etc
Notes on files: Some protocols stipulate that a fixed format of notes, such as author and agreement, should be written at the head of the file
Document-class comments: Some conventions stipulate that apis, classes, functions, etc., use document-class comments (such as JSDoc style) to follow the same style specification, such as certain Spaces and blank lines, to ensure the readability of the comments themselves
Bad comments include: comments don’t help you read the code: as in the first example of this article, you could have self-commented the code without comments and with clear naming and logic
Does not follow uniform style rules such as single-line comment length, Spaces, blank lines, for example:
// Bad single-line comment is too long to read, // parseInt was the reason my code was slow. Bitbehavior the String to coerce it to Number made it a lot faster. const val = inputValue >> 0;
// good /**
- parseInt was the reason my code was slow.
- Bitshifting the String to coerce it to a
- Number made it a lot faster. */
const val = inputValue >> 0;
Emotional comments: such as complaining, discrimination, funny, etc.
As a front-end programmer, it’s important to have a learning environment and a community. This is my front end learning exchange group 330336289 (invitation code: silence), want to learn the front end of communication, plan to in-depth understanding of this industry friends, no matter you are small white or great are welcome to join, we exchange learning together.
Three, how to write a good note
Annotation specifications
Understand the purpose and principles of annotations and develop and follow a annotation protocol to ensure the readability and consistency of annotations
Tool to ensure
Examples include using ESLint to ensure a consistent comment style and Sonar to check project comment rates
4. Annotated regulations
Here is an annotated specification for your reference:
1. [Recommended] Single-line comments use //
Comments should be written on a single line above the commented object and not appended to a statement:
// bad
const active = true; // is current tab
// good
// is current tab
const active = true;
A blank line is required above the comment line (unless the comment line is above the top of a block) to increase readability:
// bad
function getType() {
console.log(‘fetching type… ‘);
// set the default type to ‘no type’ const type = this.type || ‘no type’;
return type; }
// good
function getType() {
console.log(‘fetching type… ‘);
// set the default type to ‘no type’ const type = this.type || ‘no type’;
return type; }
// good
/ / comment lines is a block at the top of the line does not need to empty the function when getType () {/ / set the default type to ‘no type’ const type = enclosing type | | ‘no type; return type; }
2. [recommended] Multi-line comments using /**… */ instead of multiple lines //
// bad // make() returns a new element // based on the passed in tag name function make(tag) { // … return element; } // good /** * make() returns a new element * based on the passed-in tag name */ function make(tag) { // … return element; }
3. [Mandatory] There must be a space between the comment content and the comment character to improve the readability. eslint: spaced-comment
pgc-image/152531852952604e64de90b
Please click here to enter a description of the picture
4. [Recommended] Use special comments to mark
Sometimes we find a possible bug, but for some reason we can’t fix it. Or there may be some unfinished functionality somewhere, in which case we need to use corresponding special markup comments to inform future partners or ourselves. There are two kinds of special tags commonly used:
Class Calculator extends Abacus {constructor() {super(); class Calculator extends Abacus {constructor() {super(); // FIXME: shouldn’t use a global here total = 0; // TODO: total should be configurable by an options param this.total = 0; }}
5. 【 Recommended 】 Document annotations, such as functions, classes, files, events, etc., should use the JSDOC specification
Such as:
/** * class, Constructor * @constructor * @param {string} author * @param {string} constructor * @param {string} author * @param {string} author author) { this.title=title; this.author=author; } the Book. The prototype = {/ * * get the title of the Book * @ returns {string} | * / getTitle: function () {return this. The title; }, @param pageNum {number} pageNum :function(pageNum){this.pageNum=pageNum; }};
Five, tools,
There are tools available to ensure annotation quality, such as:
Eslint: Ensures a consistent comment style
ESLint is one of the most popular javascript code checking tools. ESLint has several comment rules 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: Check the annotation rate of the project
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.
Also, like Eslint, Sonar has some rules for annotation style that can be configured.
Afterword.
“Comment or not Comment, that is the question”
Understanding the purpose and principles of annotations, following a annotation protocol, and incorporating tools to ensure implementation can make annotations a good addition to your code, enhancing readability and maintainability, and thus improving code quality.