注释 | 代码注释原则
注释的书写
注释应该怎么写,写多还是写少,过多的注释甚至会干扰对代码的阅读。
写注释的一个总的原则就是注释应该尽量用来表明作者的意图,至少也应该是对一部分代码的总结,而不应该是对代码的重复或者解释。
对代码的重复或者解释的代码,看代码可能更容易理解。反映作者意图的注释解释代码的目的,从解决问题的层次上进行注释,而代码总结性注释则是从问题的解答的层次上进行注释。
推荐的写注释的过程:
1. 首先使用注释勾勒出代码的主要框架,然后根据注释撰写相应的代码。
2. 对各种主要的数据结构、输出的函数、多个函数公用的变量进行详细地注释。
3. 对代码中控制结构,单一目的的语句集进行注释。
下面是一些写注释时需要注意的要点:
- 避免对单独语句进行注释;
- 通过注释解释为什么这么做、或者要做什么,使代码的读者可以只阅读注释理解代码;
- 对读者可能会有疑问的地方进行注释;
- 对数据定义进行注释,而不是对其使用过程进行注释;
- 对于难于理解的代码,进行改写,而不要试图通过注释加以说明;
- 对关键的控制结构进行注释;
- 对数据和函数的边界、使用前提等进行注释;
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】凌霞软件回馈社区,博客园 & 1Panel & Halo 联合会员上线
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】博客园社区专享云产品让利特惠,阿里云新客6.5折上折
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步