Front-end code comment specification

Front-end code comment specification

Recently, I took over other people's code, and I really couldn't help complaining! Basically, code 0 comments, variables, and method functions all depend on guessing! Wow, really mind blowing. I have the urge to drag the former author over and tear it up!

Ok, let's get to the point. When we write code, we must add comments! Although js does not have such strict requirements on code specifications, it should also be paid attention to, otherwise the more and more codes are written, the maintainability will become worse and worse. I have to reread the code I wrote when I modify it, let alone colleagues or future handover work? It is simply harmful to others... I suggest that everyone develop a good habit of clear annotations!

1. Do not write comments because of heavy development tasks.

Annotation is a job of sharpening a knife without cutting firewood by mistake. It is just a matter of convenience, and it will be faster to read by yourself; everyone writes annotations, which is convenient for mutual understanding. If the development
task is really heavy, you can grasp the priority and put the core annotations Well-
written comments are not necessarily good programmers, but poorly written comments are definitely not good programmers!

2. You can’t stop writing comments just because you think you have good development habits

Some programmers think that they have standard naming, good development habits, clear logic, and complete package structure without writing comments. But if you name it well, it doesn’t mean that everyone can understand it, and your packaging ideas don’t mean everyone’s packaging ideas.
If it is a complex module, no matter how clear the code structure is, it will increase the difficulty of understanding. Don't be self-righteous, causing difficulty in secondary development and difficulty in reusability.

3. Where comments must be added

• Comments at the top of the business module
• Logic of Complex Modules
• Code with a relatively large upstream and downstream impact
• The names of methods, variables, and constants whose meaning or usage cannot be understood simply by the name.
• Global codes that have a large impact and modify global codes, styles, etc., mark the modification purpose and scope of influence
• Abnormal processing, such as special logic for a certain company or a certain business requirement
• Specially fix an uncommon bug, you need to add a note
• Unified management interface api, various links, parameters, etc. that the upstream and downstream depend on

4. Places that can be left without comments

• Common logic in the industry, such as the vue life cycle, commonly used built-in methods, browser methods, etc.
• Named + logically simple methods like getData, getUserInfo...

5. Comments on the top of modules and components

Comments at the top of the vue component

    <!--
      @name:模块名称
      @description:模块相关描述
      @author: hanyanshuo
      @date 2023-01-17 11:30:44
    -->
	<templte>

js file top comment

    /**
     * @description:
     * @author: hanaynshuo
     * @param {} num
     * @return {}
     * @date 2023-01-17 11:33:00
    */
    import {
    
     getName } from '@/api'

5. Single-line and multi-line comments inside and outside the method

Multi-line comments for complex methods and tool class encapsulation methods

Multi-line comments that need to annotate input parameters, output parameters, and method descriptions

/**
 * @description 日期格式化
 * @param {string} fmt YYYY-mm-dd YYYY-mm-dd HH:MM:SS
 * @param {object} date 日期对象
 * @returns {String} 日期格式化后数据
 * @date 2023-01-17 11:33:00
 */
export function dateFormat (fmt, date) {
    
    

Simple way, use single line comment

// 控件颜色改变触发事件
handelColorChange() {
    
    

variable inline comment

data() {
    
    
	return {
    
    
		btnVisible: false, // 确定按钮是否显示标识
	}
}

6. For special processing logic and code, comments must be added

For global code modification, it should be well commented and let the colleagues in the development team know.

	// index.scss文件全局修改.con的overflow属性，旨在项目页面超出时使用滚动条显示
	.con{
    
    
		overflow-y: auto

7. Modify specific bugs, business-specific logic, etc., and indicate the reason or bug id

	/**
	 * xx特殊处理，为了让用户可以修改浏览器标签页icon。xx产品于***提出。
	 */

	/**
	 * bug修改：bugID：451854641888746
	 * 影响范围：***
	 * 原因及修改项：***
	 */

Miscomment case

	// 处理icon逻辑
	handleChangeIcon()

For the above code, in actual development, it may take half a day and a day to find the cause of this problem. Leading the train of thought in the wrong direction of ambiguity. The specificity of the code is not indicated.

8. Other special notes

ALL

Use it TODO treetogether to mark codes that have not been developed or perfected, and can realize the unified management of unfinished function points.

// TODO **处理等待接口联调

to be optimized

Due to development time constraints, it is temporarily available, but there is room for optimization of the code.

Temporary note, do not delete

Some code logic that is temporarily commented out may be used in later development, and the comments are marked to prevent others from optimizing the code and deleting the comments.

Other Matters and Notes

• For complex business code, the more comments, the better, including full multi-line comments for methods, and adding internal single-line comments.
• Comments should be updated with development at any time to prevent problems that cause codes and processing logic to fail to correspond. It also becomes a poisonous comment to mislead other developers.

The above is only a personal summary of the development specification, if there are any deficiencies, please point out.