这是我参与2022首次更文挑战的第5天，活动详情查看：2022首次更文挑战」
前言
相信很多初入程序员这行的人不清楚为啥要写注释，写了有啥作用，浪费时间和精力。也有很多大神会讲到，好的代码是有很好的解释作用的，不需要注释。那今天就聊一下该不该写注释，我们又该怎么写这件事儿。
注释语法
首先复习一下前端三大件中的基本注释是怎么写的。
html注释
// html 注释
<!-- 但行注释 -->
<!--
多行注释
@name:（模块名称）
@description: add annotation doc（模块描述）
@ author: hecate (模块作者)
-->
css注释
/**
/*
* 文件顶部注释
* @description: XXX中文说明
* @author: hecate.zhu
* @update: hecate.zhu(2021-03-11 15:24)
*
*/
.cass{
display: inline;
}
/*模块注释*/
/* module: module1 by hecate.zhu*/
/*单行注释*/
/* this is a short comment */
/*
* 多行注释
* this is a short comment 1
* this is a short comment 2
*/
/* 特殊注释 */
/* TODO： xxx by hecate 2021-03-11 15:27*/
/* BUGFIX: xxx by hecate 2021-03-11 15:27*/
js注释：
// js 注释
// 单行注释：
/* 多行注释 */
/*
* 段落注释 模块注释 方法注释：
* 这里是一段注释
* 这里的注释可以连写多行
*/
How and Why
好的代码应该具备很好的可读性，但是代码可以描述 how，但它不能解释 why。注释应该写什么呢？
很明显的是，注释首要功能是阐述为什么写这段代码，也就是why，需要阐述的内容有阐述这个模块的直接缘由，这个模块的主要作用，实现了什么，如果你的出入参数不明确，应该详细的解释参数的类型以及含义。
其次，你的注释应该对晦涩难懂的代码部分，依赖的其他语法和模块的部分进行特殊说明，如果你的代码有特定的使用场景也需要特别说明，比如说依赖于jq1.21以上的版本。
eg1:以下注释写明了方法的作用，适用的场景，参数的类型、字段以及含义，隶属父类
/**
* 查询订单 支付确认页会用到
* @param {number} productId 商品id
* @memberof orderController
*/
eg2:主要阐述了方法作用，使用建议，适用场景；
// 更新用户存储信息,建议存储到cookie一份，用于网关的请求
eg3 :针对方法的可能值给出了详尽的枚举，用于更好的分析判断代码部分
// type 枚举： 'Mobile Safari' ; 'WeChat' ; 'App' ; 'QQ' ; 'ali' ;
eg4 ：css模块注释，相比而言css注释简单的多，一般只需要将模块注释或者hack或者特殊的部分扼要说明即可；
/* 面板样式*/
.m-panel{
background:#fff;
padding-left:.30rem;
margin-bottom:.20rem;
}
eg5 ：html的注释一般是针对页面结构层或者功能模块层进行注释，只建议针对特殊的部分，较大单独的模块进行注释；
<!-- m-title 头部模块 -->
<div :class="['m-title', (os=='iOS'&&uatype=='App')?'ios':'']"></div>
其他需要写注释单原则（场景）
- 澄清一些普通人无法辨认单东西，比如长单正则验证，一些复杂的设计原理。
// 手机验证正则，除了变量命名规范，也建议真滴匹配的思想描述下，如：验证13、14、15、17、18、19开头的11位的手机号码
let phoneReg=/^((13[0-9])|(14[0-9])|(15([0-9]))|(18[0-9])|(17[0-9])|190)\d{8}$/
- 书单章节一样注释，除了个别的方法以外，针对章节性的，具有连贯性单几个方法也要写下章节注释。
//以下 xx1,xx2,xx3方法实现登录逻辑
- 编写代码时保持逻辑顺畅的指南
// 判断是否需要登录
//需要登录，=> 登录验证token ，=> token有效继续执行 或 无效跳转登录
// 不需要登录=> 直接跳转
- 可以重构，开发中的技术债务可以通过注释标明便于以后单重构或者清除
// this isn't my best work, we had to get it in by the deadline
- 作为教学或者维护或者后期迭代开发的重要参考
// 垂直居中解决方案
.par{
display:table
}
.par .sub{
display:table-cell;
vertical-align:middle;
}
- 逻辑复杂
- 有一定的问题，待加补丁
总结
你还觉得注释没用吗，无论作为新手还是大神，如果想保留并继续使用自己有价值单代码，针对自己团队技术水平和代码的用途，写注释都是很有必要的哦。
