关于写好代码注释的一些建议

/*
   _     _      _     _      _     _      _     _      _     _      _     _
  (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)
   / ._. \      / ._. \      / ._. \      / ._. \      / ._. \      / ._. \
 __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
   || M ||      || O ||      || N ||      || K ||      || E ||      || Y ||
 _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._
(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)
 `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'

                         -hello world! (Version 1.5)
*/

注释是什么

程序员在开发过程中编写的与业务实现无关仅说明目标代码正在做什么的一段文本描述。这段文本描述包含在代码文件中，但不影响代码的执行，也不会带来任何附加的作用，并且在代码解释或编译执行时将忽略所有的注释内容，就好像他们并不存在一样。

为什么写注释

正确使用注释可以使代码维护变得更容易，并且帮助更快找到错误。而且在维护其他人写的代码时，注释变得尤为重要。编写完善的代码与正确运行的代码一样重要。

注释语法

根据注释的位置不同可以分成两大类

• 行注释
  1. 出现位置在代码行之上或之右，用来描述注释页面或左边部分的代码用意。
• 块注释
  1. 出现位置在方法或函数的头上，有些语言会出错在属性或类头上，它多以文档注释的身份出现。
  2. 文档注释指的是按照规定编写的注释内容可以通过特定的工具生成HTML页面文档。

不同语言之间会有差异，下面作一个列举

• 单行注释，直接添加到代码行的最前面
  1. // 双正斜线
  2. # 井号
  3. -- 双中划线
• 多行注释，在开头和结束之间的任意行中编写文本均被视为注释内容。
  1. 以 /* 开始并以 */ 结束
  2. 可以用单选注释实现注释多行的效果
• 文档注释
  1. 以 /** 开始并以 */ 结束
  2. 以 """ 开始并以 """ 结束

注释内容规范

• 注重代码的可读性
  1. 给你的方法、变量和类起一个有意义的名字，这在源头上解决了代码可读的问题。
  2. 只有不得不通过注释才能解释清楚这些代码在干什么时，才开始考虑编写注释。
  3. 要讲清楚你为什么要写这段代码，这背后有什么样的原因。
  4. 如果你正在编写由不同项目和不同团队使用的核心库，请记录使用你的API的所有假设和前提条件。
  5. 在修改现有的一段代码时要说明为什么原有的代码不能满足需要，新加的代码做了哪些改进，这在维护一个存在的项目时特别有用。
  6. 使用简单可理解的描述，让人一眼就能看明白。
  7. 不要在把注释中写上你的名字、员工ID和你的部门等等，因为这些信息可以从版本管理系统中得到。
  8. 总是在源代码版本库中提交代码的时候留下评论，特别是为什么你要添加这段代码，如果可能的话，包括任务单编号，以便任何人都可以参考任务设计时的完整细节。