Drew DeVault's blog
·
何时为代码添加注释
💡
原文英文，约1900词，阅读约需7分钟。
📝
内容提要
我的一个项目scdoc在1,133行C代码中有25个注释，占2％，而平均水平为19％，但我坚持认为我的代码编写得很好。我的编程哲学和实施注释密度各有不同，有些人将注释密度视为代码质量的代理，但我不是要说您的策略是错误的。
🎯
关键要点
- 我的项目scdoc在1133行C代码中只有25个注释，占比2%，低于平均水平19%。
- 编程哲学和注释实施在行业中差异很大，有些人将注释密度视为代码质量的代理。
- 代码注释的目的和受众不同，文档注释旨在帮助API的使用者理解函数的用法。
- 函数名称和返回类型提供了关于函数使用的重要信息，减少了对显式文档的需求。
- 实现注释的受众通常对相关标准有更深入的了解，因此可以更简洁地表达信息。
- 中等长度的散文注释用于提供上下文，解释代码的存在理由或工作原理。
- TODO注释表示未来需要解决的重要实现缺陷，通常伴随断言或问题追踪链接。
- XXX注释用于标记代码中的性能缺陷或需要注意的地方，便于后续查找和改进。
- 每个注释都考虑了目标受众和代码上下文，旨在避免冗余信息。
- 代码中注释稀少是因为作者认为代码本身提供的信息同样重要，注释应简洁明了。
➡️
