程序员必知的注释规范
前段时间就想着写写关于代码注释的博客，却迟迟没有写，一方面是因为这些实践性的内容，单靠总结意义不大；另一方面，总觉得注释是最基础的知识，一直在这里磨蹭也不是回事。但是反过来想想，最基础的反而是最欠缺的，以前做的东西，有很多存在注释不规范问题。
注释不规范的原因也很多：工程留给的时间不多；觉得繁琐，写了没什么用……这些都是浅层次的原因，深度挖掘，根本原因在自身的素质：浮躁、急功近利、舍本逐末。大家应该有过这样的经历，注释不全的情况下，自己开发的系统，6个月以后再修改，想抽自己；合作开发的系统，要修改别人的代码，想抽别人。
以下以C#为例，说说代码的注释规范，其它语言类似。规范是死的，人是活的，每个公司也会根据自己的情况制定不同的规则，把握一个原则：站在别人的角度可以看懂代码。
/*************************************************
* 作者：LIDA
* 公司：第八工作室
* 说明：本模块用于展示常用的代码注释方式
* 创建日期：2012年11月18日
* 版本号：V1.0
* **********************************************/
using System;
using System.Collections.Generic;
using System.Linq;
using System.Windows.Forms;
namespace 注释规范
{
static class Program
{
static void Main()
{
/*
* 定义用户的姓氏
* 定义用户的名字
* 定义用户的信息
*/
string firstName="LI";
string lastName = "DA";
string fullInfo;
//获取用户完整信息
NotesTest test = new NotesTest();
fullInfo=test.GetInfo(firstName,lastName);
}
}
#region 块注释：此功能块用于管理用户的个人信息
/// <summary>
/// 此类用于个人信息处理
/// </summary>
public class NotesTest
{
/// <summary>
/// 根据用户的姓氏和名字返回完整的信息
/// </summary>
/// <param name="firstName">姓氏</param>
/// <param name="lastName">名字</param>
/// <returns>完整信息</returns>
public string GetInfo(string firstName, string lastName)
{
//定义用户的住址为中国
string address="China";
///修改人：LIDA
///修改日期：2012年11月18日11:47:29
///备份：
/* 原代码
if (firstName != null)
{
return firstName;
}
*/
if (firstName != null & lastName != null)
{
//用户姓名已定义情况下返回完整信息
return firstName + " " + lastName + "live in " + address;
}
else
{
//用户姓名未定义情况下返回未定义提示信息
return "User's information is undefined!";
}
}
}
#endregion
}
行注释
这个是最简单的注释形式，用于对一行或多行的代码注释，一般用于描述关键语句或变量的内容，如上：
//定义用户的住址为中国 string address="China";
修改注释
修改注释和添加注释相同，都是要指出添加/修改者、时间、原内容、添加/修改的内容，方便以后调试、维护和责任的定位等，如上：
///修改人：LIDA
///修改日期：2012年11月18日11:47:29
///备份：
/* 原代码
if (firstName != null)
{
return firstName;
}
*/
分支注释
分支注释用于解释分支或循环的意义，为了使方便理解代码中的逻辑，如上：
if (firstName != null & lastName != null)
{
//用户姓名已定义情况下返回完整信息
return firstName + " " + lastName + "live in " + address;
}
else
{
//用户姓名未定义情况下返回未定义提示信息
return "User's information is undefined!";
}
函数注释
函数注释需要函数功能、参数和返回值信息，在函数调用时可直接看到这些注释内容，如上：
/// <summary>
/// 根据用户的姓氏和名字返回完整的信息
/// </summary>
/// <param name="firstName">姓氏</param>
/// <param name="lastName">名字</param>
/// <returns>完整信息</returns>
块注释
多个函数或类完成相同的功能，可以将其放到一起加上块注释，块注释可以很直观的展现一组函数或类的功能：
#region 块注释：此功能块用于管理用户的个人信息 /*native code*/ #endregion
类注释
如其名，主要是解释一个类的作用，例子中的写得较为简单，也可以加上作者、日期等信息。
代码这么简单，还写注释，不是无痛呻吟吗？这是为了举例而举例，所以非常简单，看一个去除了注释的程序段，你作何感想？
public DataSet QueryPatientAndSections(TeamPatient teamPatient){
DataTable dtPatient = new DataTable();
DataSet dsInfo=new DataSet ();
if (teamOrSingle.IsTeamOrSingle(teamPatient) == "team")
{
dtPatient = teamPatientDAO.QueryPatientInfoByID(teamPatient);
dtPatient.TableName = "PatientInfo";
dsInfo.Tables.Add(dtPatient);
string teamID = dtPatient.Rows[0]["团队号"].ToString();
Team entityTeam = new Team();
entityTeam.TeamID = teamID;
DataTable dtTeam = teamDAO.QueryTeamInfoByTeamID(entityTeam);
dtTeam.TableName = "TeamInfo";
dsInfo.Tables.Add(dtTeam);
SelectSection entitySelectSection=new SelectSection();
entitySelectSection.ExaminationID=teamPatient.ExaminationID ;
DataTable dtSelect = selectSectionDAO.QueryOrderItemByID(entitySelectSection);
dtSelect.TableName = "SelectSection";
dsInfo.Tables.Add(dtSelect);
}
else {
SinglePatient entitySinglePatient = new SinglePatient();
entitySinglePatient.ExaminationID = teamPatient.ExaminationID;
dtPatient = singlePatientDAO.QueryPatientInfoByID(entitySinglePatient);
dtPatient.TableName = "PatientInfo";
dsInfo.Tables.Add(dtPatient);
SelectSection entitySelectSection = new SelectSection();
entitySelectSection.ExaminationID = teamPatient.ExaminationID;
DataTable dtSelect = selectSectionDAO.QueryOrderItemByID(entitySelectSection);
dtSelect.TableName = "SelectSection";
dsInfo.Tables.Add(dtSelect);
}
return dsInfo;
} 如果加上注释呢？
/// <summary>
/// 根据体检号查询团队信息、团队个人信息、团队个人所选科室
/// </summary>
/// <param name="teamPatient">使用TeamPatient中的体检号</param>
/// <returns>个人或团队个人的信息表和所选科室表</returns>
public DataSet QueryPatientAndSections(TeamPatient teamPatient){
//建立用于存放病人信息的表
DataTable dtPatient = new DataTable();
//建立存放多人信息的dataset
DataSet dsInfo=new DataSet ();
/*判断此体检人是个人还是团体中的个人
*如果为个人则根据个人表中的信息进行处理
*如果是团体个人则根据团体个人表处理
*/
if (teamOrSingle.IsTeamOrSingle(teamPatient) == "team")
{
//团体中的个人
//根据ID查询个人信息
dtPatient = teamPatientDAO.QueryPatientInfoByID(teamPatient);
dtPatient.TableName = "PatientInfo";
//将个人信息添加到dsInfo
dsInfo.Tables.Add(dtPatient);
//根据团队号查询团队信息
string teamID = dtPatient.Rows[0]["团队号"].ToString();
Team entityTeam = new Team();
entityTeam.TeamID = teamID;
DataTable dtTeam = teamDAO.QueryTeamInfoByTeamID(entityTeam);
dtTeam.TableName = "TeamInfo";
//添加团队信息到dataset
dsInfo.Tables.Add(dtTeam);
//根据ID查询所选科室
SelectSection entitySelectSection=new SelectSection();
entitySelectSection.ExaminationID=teamPatient.ExaminationID ;
DataTable dtSelect = selectSectionDAO.QueryOrderItemByID(entitySelectSection);
dtSelect.TableName = "SelectSection";
//添加所选科室到dataset
dsInfo.Tables.Add(dtSelect);
}
else {
//如果是个人
//根据ID查询个人信息
SinglePatient entitySinglePatient = new SinglePatient();
entitySinglePatient.ExaminationID = teamPatient.ExaminationID;
dtPatient = singlePatientDAO.QueryPatientInfoByID(entitySinglePatient);
dtPatient.TableName = "PatientInfo";
//添加个人信息到dataset
dsInfo.Tables.Add(dtPatient);
//根据id查询所选科室
SelectSection entitySelectSection = new SelectSection();
entitySelectSection.ExaminationID = teamPatient.ExaminationID;
DataTable dtSelect = selectSectionDAO.QueryOrderItemByID(entitySelectSection);
dtSelect.TableName = "SelectSection";
//添加所选科室到dataset
dsInfo.Tables.Add(dtSelect);
}
//将个人信息以及所选科室返回
return dsInfo;
}
写好注释，刚开始可能会多花点时间，但是在修改和维护时，会节省非常多的时间在理解程序上，这一点，是非常值的。还是开头那句话，实践性的内容，单靠总结意义不大，重在动手去做，不嫌麻烦，不舍本逐末。