foreword
I believe that all friends are familiar with comments, but it is this small comment that makes many friends love and hate like project documents. I don't like to write notes, and I hate when others don't write notes. Here we will JavaScriptdiscuss CSSthe annotations of and , and hope that through this article, you can regain your love for annotations and make coding as fun as the stars.
1. Grammar
1. CSS comments
/* css 注释 */
2. JavaScript comments
// 单行注释
/**
* 多行注释，注意第一行最好用两个 *
* ...
*/
/*
当然，除了两端的 * 必须加以外，其他的 * 不加也行
...
*/
2. Basic use
1. Single-line comments
Under normal circumstances, single-line comments will appear directly above the code to serve as a reminder:
/* 用注释备注 CSS 类名的功能 */
/* 顶部组件 */
.hd {
position: fixed;
width: 100vw;
}
/* 版心 */
.container {
margin: 16px auto;
width: 1200px;
}
// 用单行注释备注简单的信息
const userName = ""; // 用户名
const userAvatar = ""; // 用户头像
// xxx函数
const myFunction = () => {
};
2. Multi-line comments
Multi-line comments are generally used when too much information needs to be remarked, and they often appear near JavaScriptfunctions . First ask a question: Why use multi-line comments, is it not good to use single-line comments? Let's take a look at the following code:
// xxx函数
const myFunction = ({
id, name, avatar, list, type }) => {
// 此处省略 30 行代码
};
Friends may have seen that a function with five parameters and a few lines of code inside has only a short line of comments. Maybe you can remember the purpose of this function, the type of parameters and whether they are required to be passed when developing. But if you look back at the previous code after a period of time, then the short comment may become your obsession. Not to mention that there are no comments, it's cool not to write comments, and look back at the code crematorium. The purpose of writing comments is to improve the readability of the code. In contrast, the following annotation is much clearer:
/**
* 调整滚动距离
* 用于显示给定 id 元素
* @param id string 必传 元素 id
* @param distance number 非必传 距离视口最顶部距离(避免被顶部固定定位元素遮挡)
* @returns null
*/
export const scrollToShowElement = (id = "", distance = 0) => {
return () => {
if (!id) {
return;
};
const element = document.getElementById(id);
if (!element) {
return;
};
const top = element?.offsetTop || 0;
window.scroll(0, top - distance);
};
};
For complex functions, multi-line comments in a unified format should be added to the function declaration, and single-line comments should also be added to the internal complex logic and important variables. The two complement each other and complement each other. The multi-line comment format of a function declaration is generally as follows:
/**
* 函数名称
* 函数简介
* @param 参数1 参数1数据类型 是否必传 参数1描述
* @param 参数2 参数2数据类型 是否必传 参数2描述
* @param ...
* @returns 返回值
*/
The advantage of multi-line comments is clarity, but the disadvantage is that it is cumbersome (JavaScript function comment templates can be generated with the help of an editor). It is recommended to use single-line comments for functions with simple logic, and multi-line comments for functions with complex logic and public/utility functions.
Of course, a good variable/function name can also reduce the reader's thinking cost, you can move to my article: "Elegant Naming" .
3. Advanced use
No matter in cssor JavaScriptin , when there are more and more codes, it becomes more and more troublesome to find the code to be changed. Therefore, it is necessary for us to organize the code by module, and use comments at the top of each module, and use blank lines to separate at the end.
/* 以下代码仅为示例 */
/* 模块1 */
/* 类名1 */
.class-a {
}
/* 类名2 */
.class-b {
}
/* 类名3 */
.class-c {
}
/* 模块2 */
/* 类名4 */
.class-d {
}
/* 类名5 */
.class-e {
}
/* ... */
// 以下代码仅为示例
// 模块1
// 变量1
const value1 = "";
// 变量2
const value2 = "";
// 变量3
const value3 = "";
// 函数1
const myFunction1 = () => {
};
// 模块2
// 变量4
const value4 = "";
// 变量5
const value5 = "";
// 变量6
const value6 = "";
// 函数2
const myFunction2 = () => {
};
// ...
The effect is there, but it seems not obvious, so we add -or =to try to split:
/* ------------------------ 模块1 ------------------------ */
/* 类名1 */
.class-a {
}
/* 类名2 */
.class-b {
}
/* 类名3 */
.class-c {
}
/* ------------------------ 模块2 ------------------------ */
/* 类名4 */
.class-d {
}
/* 类名5 */
.class-e {
}
/* ... */
// 以下代码仅为示例
/* ======================== 模块1 ======================== */
// 变量1
const value1 = "";
// 变量2
const value2 = "";
// 变量3
const value3 = "";
// 函数1
const myFunction1 = () => {
};
/* ======================== 模块2 ======================== */
// 变量4
const value4 = "";
// 变量5
const value5 = "";
// 变量6
const value6 = "";
// 函数2
const myFunction2 = () => {
};
// ...
It can be seen intuitively that the annotation segmentation effect of the extended version is better and the degree of discrimination is higher. High-quality code often requires the most unpretentious comments to segment. JavaScriptThe comment "separation line" in it suggests using multi-line comments.
"Gorgeous" dividing line:
/* ------------------------ 华丽的分割线 ------------------------ */
/* ======================== 华丽的分割线 ======================== */
4. Expansion
If a worker wants to do a good job, he must first sharpen his tools. Next, I would like to recommend several VSCodeeditor plugins for comments.
1. Better Comments
Plug-in introduction: You can change the color of the comment, there are four highlighted colors (red, orange, green, blue by default) and a black with strikethrough. The color can be modified in the plugin configuration. The picture below shows the example color and my usage in the project, and one comment corresponds to one situation.
A must-have plug-in for coders who like bells and whistles, which can effectively improve the resolution and aesthetics of annotations, and fall in love with annotations ever since. It only needs to add one or more characters to change the comment color, and it works out of the box.
// ! 红色的高亮注释,双斜线后加英文叹号 ! 配置
// todo 橙色的高亮注释,双斜线后加 todo 函数
// * 绿色的高亮注释,双斜线后加 * 变量
// ? 蓝色的高亮注释,双斜线后加英文问号 ? 组件
// // 黑色带删除线的注释,双斜线后加双斜线 // 说明
2. koroFileHeader
Plug-in introduction: add comments at the head of the file, add function comments at the cursor, and add comment patterns such as Buddha Blessing Never BUG, Divine Beast Body Protection, etc. with one click.
3. JavaScript Comment Snippet
Plug-in introduction: It can quickly generate JavaScript comments, which is unpopular but easy to use.
summary
I have to say that comments are really important in the coding process. In order to write more elegant and maintainable code, we should also write the most important information into comments. A project's README.markdownand the comments in the project are like the project's manual , which allows non-project developers to understand the meaning of the code and the idea of coding faster. Let the code make us, let the code change the world, and let the comments accompany me!