程序员必会技能-注释

#如何看待程序员不写注释？#

1.我的注释说

我们在开发中少不了要跟注释打交道，注释在编程中扮演着重要的角色，可以帮助大家理解代码的意图和逻辑，特别是在处理复杂的代码或项目时。以前在做日本项目的时候，客户对代码注释也是有强制要求的，前期还会先对开发成员进行注释等规范的考试，保障以后项目交付后的可维护性。

良好注释的好处

• 代码可读性： 注释可以帮助提高代码的可读性。通过解释代码的逻辑、目的和设计决策，使其他开发者更容易理解代码。这对于维护和交接项目特别重要，尤其是本身难以理解或逻辑复杂的代码块，更是需要提供额外的解释。

• 文档生成:： 注释可以用来自动生成代码文档。这些文档对于新成员了解项目、API或库的目的是非常有帮助的。

• 代码走查： 注释在代码走查中也很有用。它们可以帮助团队成员理解代码的更改，并确保每个人都对代码的意图有相同的理解。

过度、无效注释不可取

下面举一个过度+无效注释的例子，大家不要这么来哈：

// if condition1 is true then do this  
// else if condition2 is true do that  
// else do something else  
// fk, my boss let me write notes, it's do nothing. haha
if (condition1) {  
  // do something  
} else if (condition2) {  
  // do something else  
} else {  
  // else I won't tell you, you guess what
}

不写注释的坏处

人的记忆是有限的，可能过了几周、几个月后，你再来改这段代码的时候，就根本不知道里面什么逻辑，就不会不敢修改，怕引发其他未知的bug。或者团队成员来改的时候，也是无从下手。重要代码不写注释引发上面的问题屡见不鲜，不要对自己过分的自信，时间会让你忘记一切哈。
当然如果你是想靠这个让人看不懂的代码，来体现你在团队重要性的话，则不在我们讨论范围哈。

2.不写注释的原因是什么

程序员不想写注释的原因可能有以下几个方面：

• 时间压力：在完成代码的同时，添加注释需要额外的时间，而程序员往往面临时间压力，可能更倾向于将时间用于实现功能。
• 认为代码足够清晰：有些程序员可能认为他们的代码逻辑已经足够清晰，无需注释。
• 维护问题：有些人认为注释会使代码看起来更混乱，增加代码的维护成本。
• 缺乏技能：部分程序员可能缺乏写注释的技能和经验，不知道应该在何处添加注释，以及如何编写清晰、有用的注释。

3.如何才能写出漂亮的注释

写好注释要遵循的原则

• 了解代码：首先，你需要理解你的代码在做什么。这将帮助你确定哪些部分需要注释以及如何最有效地进行注释。
• 选择合适的注释类型：根据代码的具体情况，选择适合的注释类型。例如，对于不易理解的复杂逻辑或算法，可以使用解释性注释；对于需要稍后修复或优化的代码，可以使用TODO注释；对于需要关注的问题，可以使用警告或注意注释等。
• 写清楚简洁的注释：一旦你理解了代码并选择了合适的注释类型，就应该开始写注释了。注释应该清晰、简洁，只包含重要和必要的信息。避免在注释中重复代码，而是解释代码的目的、逻辑或其它需要注意的事项。
• 遵循一致的格式和风格：在整个代码库中保持一致的注释格式和风格可以使代码更易于阅读和理解。可以根据项目或公司的要求，也可以自己定义合适的格式和风格。
• 遵循编程规范：使用适当的命名、缩进、空格和括号等编程规范可以使代码和注释都更加易读。
• 保持注释最新：当代码更改时，需要更新相关的注释。如果可能的话，最好在更改代码的同时更新注释，这样可以避免不一致和混淆。
• 使用有意义的注释：比如"TODO"，“FIXME”，"HACK"等。这些注释虽然对理解代码没什么帮助，但是它可以让人家理解该处遗留的一些问题或者修改了哪个bug。
• 避免写出感觉像是机器生成的注释：例如，一些开发者喜欢为每个方法或每个类生成 Javadoc 或其它类型的自动文档。虽然这些工具可以帮助生成有用的文档，但它们也会引入很多不必要的噪声。确保你的注释是有意义的，可以帮助人类理解代码，而不是感觉像是机器生成的。
• 务必在复杂或者重要的代码上加注释：当你遇到一个可能需要做出改变的复杂问题时，花时间在注释中详细解释你的决策以及你为何做出这样的决策是很有价值的。这不仅可以帮助别人理解你的代码，还可以为将来的维护者提供一个很好的起点，让他们知道可以从哪里开始修改代码。
• 测试你的注释：在你写了一段代码或添加了新的注释后，试着通过阅读和理解注释来检查它们是否有效。如果可能的话，尝试从另一个角度（例如，从初学者的角度）来看待你的注释，看看它们是否真的易于理解。

常见注释例子（java代码）

• 类注释：

/**  
 *  订单类
 * 	用户下单关联的对象类
 * @author yuan
 * @since 2023-10-19  
 */  
public class Order { 

• 方法、参数注释

/**  
 * 计算两个数的和 
 *   
 * @param a 加数
 * @param b 被加数  
 * @return 返回计算和的结果 
 */  
public int add(int a, int b) {  
    return a + b;  
}

• 类属性、简单行注释

	// 姓名
    private String name;  
	/**  
     * 手机号
     */  
    private String mobile;  

	if (condition) {
		// 如果xx条件成立，才统计xx
	}

有的编码习惯喜欢在属性上的注释使用上面手机号形式，我是感觉这样太浪费代码行数了，一行可以解决的就没必要多行，但是这种在生成文档的时候会有用，不过现在也很少人用javadoc来生成文档，java开放api接口的话，文档一般都是基于swagger的扩展，如SpringDoc、Knife4j等。

• 复杂代码块注释

/*
	我在这里说明下面代码执行逻辑及注意事项
*/
calculateAvg();

• 待办注释：标注当前版本先不实现，后续版本再考虑

// TODO 当前版本先不实现，后续版本再考虑

以上就是我对注释的理解，如果觉得内容对你有用，劳烦多多点赞+分享哦~~