代码注释和格式化的 10 个最佳实践
代码注释和格式化的目的都是为了让代码更容易阅读和理解,提升了代码的可维护性,下面是 10 个关于代码注释和格式的 10 个最佳实践(特别是 Java)。
代码注释
注释是代码的一部分,在统计代码行时注释也包含在内,非常重要。一段无任何注释的代码很可能是完全无用。尽管有些极端的建议说代码应该有自注释的方法,不过我们还是建议注释良好代码的必要条件。
- 只在需要的时候编写注释
- 不要为每行代码都编写注释,无用而且降低可读性,例如:
- int count = 0; // 给 count 变量设置初始值,这人人都能看懂 (?!?)
- 缺少注释会增加代码维护难度和实践,首先变量和方法名应该是可理解和自注释的,下面是两个不好的例子:
- int s = sqrt(v1) + v2 / v3 + fread(s). getChar(0) //(?!?)
- List<int> getVal(int val, int len, String op) //(?!?)
- 不要编写错误的注释,比无注释更可恶
- 为非常重要的变量编写注释,而不是使用自文档风格
- 为所有的公开的方法和接口编写注释,这是必须的
- 应该删除文档中一些无用的内容,例如 todo 之类的
代码格式化
很多的开发工具都提供代码格式化的功能,例如 maven checkstyle ,并且这些格式化操作可在代码保存时自动进行,但这些工具格式化的规则多少跟每个公司的要求不同,所以在使用前应该进行设置以便跟公司代码格式规范一致。
下面是一些对于代码格式化的建议:
- 统一使用括号的方式:你可以在同一行使用括号或者换一个新行,这都没关系,关键是要一致。
- 统一空行使用的规则,例如方法结束后可以来三个空行,是否每行代码都用空行隔开或者不,这些依照自身的习惯而行,但要统一。
- 缩进的处理方式统一
- 每行的字符数应该有所限制,提升代码可读性,一般 80 左右个字符最为合适
- 代码中的空格使用要一致,例如:
- 操作符和变量:
- a += b , c = 0; (a == b)
- 语句和括号之间:
- if (value) {, public class A {
- 循环之中:
- for (int i = 0; i < length; i++)
- 类型转换:
- (int) value , (String) value
【推荐】国内首个AI IDE,深度理解中文开发场景,立即下载体验Trae
【推荐】编程新体验,更懂你的AI,立即体验豆包MarsCode编程助手
【推荐】抖音旗下AI助手豆包,你的智能百科全书,全免费不限次数
【推荐】轻量又高性能的 SSH 工具 IShell:AI 加持,快人一步
· 如何编写易于单元测试的代码
· 10年+ .NET Coder 心语,封装的思维:从隐藏、稳定开始理解其本质意义
· .NET Core 中如何实现缓存的预热?
· 从 HTTP 原因短语缺失研究 HTTP/2 和 HTTP/3 的设计差异
· AI与.NET技术实操系列:向量存储与相似性搜索在 .NET 中的实现
· 周边上新:园子的第一款马克杯温暖上架
· Open-Sora 2.0 重磅开源!
· 分享 3 个 .NET 开源的文件压缩处理库,助力快速实现文件压缩解压功能!
· Ollama——大语言模型本地部署的极速利器
· DeepSeek如何颠覆传统软件测试?测试工程师会被淘汰吗?