目录

一、关于写备注这件事

注释规范

备注时效性

对复杂逻辑的注释应该完善

README

二、写代码之前明确需求

 良好的开发习惯于个人可以在开发中起到事半功倍的效果，于团队则是共同遵守维护的规则可以在协作开发时减少很多不必要的沟通，而后续定位问题或者业务功能维护时又可以很大幅度的提升效率，所以有必要将碰到的一些问题记下来，希望自己同一个问题不用错两次。

一、关于写备注这件事

总有段子说程序员讨厌别人不写备注更讨厌别人喊自己写备注，段子好玩但可以想象接手一个项目结构紊乱代码量也多的项目却没有备注的时候该有多绝望。

想斩断一个莫比乌斯环最好竖着来一刀。都在期待看到的代码可维护性高并且配有便于理解的备注，不如就从自己这里下手。

注释规范

1.说人话，说人看了之后最短时间能明确这段代码做了什么的话。

2.函数、方法在开始前注明为什么会有这个方法以及入参出参返回值。下图为来自jsDoc中对于函数入参备注的规范说明

3.保持在新的一行及缩进同上下文对齐的地方开始一段备注，行尾的备注会让代码看起来很乱。

4.文件头部注释及修改后的修改人信息

/*
 * @File name: util.js
 * @Author: Micah
 * @Version: 1.0
 * @Date: 2021-11-21
 * @Description: utility functions

 * @Modifier：张三
 * @Modification time：2022-08-08
 * @Modify content：add functions
 */

备注时效性

备注需要及时更新，错误的备注不如不写。

修改了原有功能，方法的出入参或者临时添加只希望自己看到的备注都应该被及时更正。

对复杂逻辑的注释应该完善

虽然开发中会通过各种设计模式尽可能的避免复杂的 if...else... 和大段的循环等逻辑复杂的场景，但如果确实碰到了，请保证你的注释会让你在三个月之后需要重新维护代码再看到这段的时候可以笑着看完。

README

对于新项目或者新建模块而言一个 README.md 是必要的，但这里只谈新建模块。这个模块包含的功能，存在的原因，使用说明甚至基本原理都可以囊括进去，一个文件省却后续维护人包括自己的一头雾水，写完自己也会有种成就感，何乐而不为。

二、写代码之前明确需求