什么时候需要注释，怎么注释？
2016-06-05 本文已影响391人
b64c74899092
什么时候要写注释如何写好注释
别给糟糕的代码加注释----重新写吧。
注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败。注释总是一种失败，我们找不到不用注释就能表达自我的方法，所以总要有注释，这并不值得庆幸。
为什么注释不好？因为注释会撒谎，注释存在的时间越久，就离其描述的代码越远，越来越变得全然错误。原因很简单。程序员不能坚持维护注释。
代码在变动在演化，从这里移到那里。注释不总是随之搬动。注释常常会和所描述的代码分隔开来，越来越不准确。
注释不能美化糟糕的代码
写注释 常见动机之一是糟糕代码的存在。带有少量注释的整洁而有表达力的代码要比带有大量注释的零碎而复杂的代码像样的多。
用代码来阐述
很多时候只要创建一个描述与注释相同意义的一个函数就可以。
好注释
有些注释也时必须的。
法律信息
有时候公司代码规范要求编写与法律相关的注释。例如，版权与著作权声明就是必须和有理由在每个源文件开头注释处放置的内容。
提供信息的注释
有时候用来注释基本信息也有其用处。例如，注释某个抽象方法的返回值。这类注释有时有用，但更好的方法是尽量利用函数名称来传达信息。
对意图的解释
有时，注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。
阐释
有时，注释把某些晦涩难懂的参数或者返回值翻译为某种可读形式，也是有用的。通常，更好的方法是尽量让参数返回值自身足够清晰；但是如果参数或返回值是某个标准库的一部分，或者是你不能修改的代码，帮助阐释其含义的注释就会有用。
警示
有时，用于警告其他程序员会出现某种后果的注释也时有用的。
TODO注释
有时，有理由用//TODO形式在源代码中放置要做的工作列表。
TODO是一种程序员认为应该做，但是由于某些原因目前还没有做的工作。
放大
注释可以用来放大某种看起来不合理的代码。
