代 码 注 释（Code comments）
在理解三层和机房三层+设计模式时，特别是三层运行时，师傅狠狠的指导了一
番，必须要一行一行运行原则，和怎么运行的，自己要能说出是怎么运行出来。 当初查
了一些网上资料，稂莠不齐，所以自己总结了一些代码注释的原则，还请多多指点：
代码的标准是英文，它的母语就是英文，现在不论是中国人、日本人还是俄国人在
开发软件，为了更好的理解和开发软件，都很有必要写一些相应的注释，为了更好的更
改、维护等工作，代码注释不是必须的，但是它可以提高程序的可读性，建议养成写注释的习惯，基本的注释要求在20%~30%左右，有了代码的注释到时候自己也能更快更好的理解。
规范示例：
/头文件的头注释
/*************************************************
Copyright (C), ２０１３, DanielStark
File name: // 文件名
Author: Version: Date: 2013.3.02 DanielStark // 作者、版本及完成日期
Description: <pre name="code" class="csharp">/*************************************************
Function: // 函数名称
Description: // 函数功能、性能等的描述
Calls: // 被本函数调用的函数清单
Called By: // 调用本函数的函数清单
Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序）
Table Updated: // 被修改的表（此项仅对于牵扯到数据库操作的程序）
Input: // 输入参数说明，包括每个参数的作
// 用、取值说明及参数间关系。
Output: // 对输出参数的说明。
Return: // 函数返回值的说明
Others: // 其它说明
*************************************************/
// 用于详细说明此程序文件完成的主要功能，与其他模块 // 或函数的接口，输出值、取值范围、含义及参数间的控 // 制、顺序、独立或依赖等关系 Others: // 其它内容的说明 Function List: // 主要函数列表，每条记录应包括函数名及功能简要说明 1. .... History: // 修改历史记录列表，每条修改记录应包括修改日期、修改 // 者及修改内容简述 1. Date: Author: Modification:
*************************************************/
源文件头部应进行注释，列出：版权说明、版本号、生成日期、作者、模块目的/功能、主要函数及
其功能、修改日志等。
示例：下面这段源文件的头注释比较标准，当然，并不局限于此格式，但上述信息建议要包含在内。
/************************************************************
Copyright (C), 2013.3.02 DanielStark, 信息技术提高班
FileName: test.cpp
Author: Version : Date:
Description: // 模块描述
Version: // 版本信息
Function List: // 主要函数及其功能
1. -------
History: // 历史修改记录
<author> <time> <version > <desc>
David 96/10/12 1.0 build this moudle
**********************************************************/
函数头部应进行注释，列出：函数的目的/ 功能、输入参数、输出参数、返回值、
调用关系（函数、表）等
示例：下面这段函数的注释比较标准，当然，并不局限于此格式，但上述信息建议要包
含在内
/*************************************************
Function: // 函数名称
Description: // 函数功能、性能等的描述
Calls: // 被本函数调用的函数清单
Called By: // 调用本函数的函数清单
Table Accessed: // 被访问的表（此项仅对于牵扯到数据库操作的程序）
Table Updated: // 被修改的表（此项仅对于牵扯到数据库操作的程序）
Input: // 输入参数说明，包括每个参数的作
// 用、取值说明及参数间关系。
Output: // 对输出参数的说明。
Return: // 函数返回值的说明
Others: // 其它说明
*************************************************/
最好的习惯：边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的
一致性
代码注释原则:
1：避免在一行代码或表达式的中间插入注释。
说明：除非必要，不应在代码或表达中间插入注释，否则容易使代码可理解性变差。
2：通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构，使代码
成为自注释的。
说明：清晰准确的函数、变量等的命名，可增加代码可读性，并减少不必要的注释。
3：在代码的功能、意图层次上进行注释，提供有用、额外的信息。
说明：注释的目的是解释代码的目的、功能和采用的方法，提供代码以外的信息，帮助
读者理解代码，防止没必要的重复注释信息。
示例：如下注释意义不大。
/* if receive_flag is TRUE */ if (receive_flag) 而如下的注释则给出了额外有用的信息。 /* if mtp receive a message from links */ if (receive_flag)
4：在程序块的结束行右方加注释标记，以表明某程序块的结束。
说明：当代码段较长，特别是多重嵌套时，这样做可以使代码更清晰，更便于阅读。
示例：参见如下例子。
if (...)
{
// program code
while (index < MAX_INDEX)
{
// program code
} /* end of while (index < MAX_INDEX) */ // 指明该条while语句结束
} /* end of if (...)*/ // 指明是哪条if语句结束
5：注释格式尽量统一，建议使用"/* …… */"。
6：注释应考虑程序易读及外观排版的因素，使用的语言若是中、英兼有的，建议多使用
中文，除非能用非常流利准确的英文表达。
说明：注释语言不统一，影响程序易读性和外观排版，出于对维护人员的考虑，建议使用中文（自己的母语）。
注释总结；
1.一目了然的情况不写注释。记得刚进入软件开发行业的时候，日本客户的编码规约上就写着，当有
if、while、for的时候，一定要写明判断和循环的原因，那时幼稚的我一定会有这样的代码：这不是一句废话吗？但凡是个程序员都会知道这段代码是在做什么，可是我却写了很多年，回想一下真是傻的要命，这简直是在浪费键盘！
2.错误的注释还不如没有注释。很多时候人们会复制别人的代码，或者是被别人复制，复制的过程中，很容易忘记修改成符合自己的注释，记得有一次客户发邮件质问我们，为什么注释和代码不符，哦！那是抄袭的，忘记改了。还有一次客户的正式环境险些宕机，找到了问题SQL，发现此问题SQL上有段注释，-- 某年某月某日 某某某 修改，哈哈，貌似问题SQL的作者被抓到了，可是事实是这段是被另外一个人copy去的，冤枉死了～大晴天都可以下雪了！所以对复制来的代码中的注释一定要慎重啊。
3.对难以理解的代码进行注释。有些处理可能会很复杂，如果不记录下来可能自己都不会再记得，别人再看的时候也会非常麻烦，这里可以简单描述一下，切忌不可像写作文一样，反而让人更加迷惑。
4.不得不写注释的地方有待重构。复杂而又难以理解的代码我想都是有重构的必要的，把复杂的东西拆成若干个函数，各执其责，再复杂的代码也可以变的简单，我想，都变的很简单的时候，也就没有必要解释复杂逻辑了吧。
5.对类、函数、函数的形参进行注释。要快速知道你的程序的整体结构，除了类和函数的合理命名外，就是对类和函数进行合理的说明，我想，如果命名上已经贴切的不能再贴切了，那不写注释也无所谓了吧，但写上也是个很不错的想法。
6.努力写出自解代码。自解代码顾名思义，就是不用注释就可以很好的明白代码的含义，写出能让人容易懂的代码，比不得不写注释来解释的代码优秀的多。
总结：不写注释就可以看懂的代码，才是优秀的代码。
总结：
注释不仅仅能够增强代码的可读性，而且写注释的过程是一个思考代码功能的过
程，与代码比起来，寥寥几句注释更能够将功能抽象描述出来。从反面角度来说，如果一段代码的注释很难写，也就证明了该段代码所要实现的功能比较混乱，该段代码也就需要重写了。
PS：注释作为一种引导思维的手段，应该写在代码前，而不是代码后。
引用大师级的话：
最差的代码，没有注释
凑合用的代码，随意注释
合格的代码，注释和代码一致，并有助于代码的理解和维护
优良的代码，只做必要的注释