关于程序中注释书写格式.doc

关于程序中注释书写格式 为了大家今后工作方便，暂约定程序的注释照以下格式书写：1、 程序文件注释： 放在程序名称空间引用（using System.IO;）的上面，主要写公司的版权、文件创建的时间、文件的主要内容、文件的名字、文件的创建标识（创建人姓名）、文件修改的时间、文件修改时的修改标识（修改人姓名）、文件修改的修改原因等（详情见文档后备注示例）；2、 类的作用注释： 放在类（类、接口、枚举、结构体）的声明上方，主要描述类的作用。如果类的结构比较复杂，也应该添加类的使用示例和类的流程（其它特点）（详情见文档后备注示例）；3、 类的私有全局重要变量注释： 放在类的全局变量声明上方，主要需要注释通过命名不能正确理解的全局私有或公有（包含受保护等）变量。如果是object（特殊数组等）型变量，内部使用时结构比较复杂或有规定，需要简要的说明一下内部结构。4、 类的属性的注释： 放在类的属性声明上方，简要说明属性的类型和主要作用。5、 类的公有方法的注释： 主要说明方法的作用，方法各参数的意义和要求，方法的返回值及各种可能的返回值的特殊意义，方法可能会产生的异常，如果需要，则可以写出方法的使用示例；6、 类的私有方法或重要算法的注释： 除了需要说明公有方法所要求的之外，如果算法、数学运算比较复杂，需要写出算法或数学方法的理论过程或推导过程；如果算法比较长，要尽可能的细分成逻辑块，并填写适当的注释；对于方法中的重要变量也要添加适当的注释，特别是对方法的结果或方法某一段的结果的方法内部不易理解的变量要添加合适的注释；对于特别复杂（重要）的方法，要添加适当的流程图或文档，给以充分的文字、图解等说明；7、 文件、类或类的方法修改后的注释的变更： 对于对文件或类（包括接口、枚举、结构体）或类的方法修改后，要添加修改后的相注释，要写清修改的时间、修改标识（修改人姓名）、修改的原因等一切必要的信息和一切必要变更的信息（类、方法的流程）；注释示例类：/*-/ Copyright (C) 2010北京中奥维科技发展有限公司/ 版权所有。 / 文件名：AnnotationDemo1.cs/ 创建日期：2010-8-21/ 文件功能描述： 注释示例1,在这个文件中有关于类（类、枚举、接口、结构体） 和 类的属性、/类的方法、类内部的全局变量、方法内部的重要变量的注释格式；/ / / 创建标识：Zhaozhijian/ 修改标识：/ 修改描述：/ 修改标识：/ 修改描述：/-*/using System;using System.Collections.Generic;using System.Linq;using System.Text;namespace AnnotationDemo / / 注释类示例1, / public class AnnotationDemo1 : IAnnotation private string m_DemoName; / / 示例名字 / public string DemoName get return m_DemoName; set m_DemoName = value; private string m_DemoContent; / / 示例的的内容 / public string DemoContent get return m_DemoContent; set m_DemoContent = value; private DateTime m_CreateDate; / / 示例创建日期 / public DateTime CreateDate get return m_CreateDate; private DateTime m_LastChangedDate; / / 示例最后一次修改的时间 / public DateTime LastChangedDate get return m_LastChangedDate; set m_LastChangedDate = value; private PrizeLevel m_PrizeLevel; / / 注释示例等级 / public PrizeLevel PrizeLevel get return m_PrizeLevel; set m_PrizeLevel = value; / / 创建注释示例类对象，并记录注释示例创建时间 / public AnnotationDemo1() this.m_CreateDate = DateTime.Now; / / 通过重载+运算，提升注释示例的等级 / / 要提升注释示例等级的注释示例 / / 当前需要提升的注释示例的等级最高时，错误提升信息提示以异常的方式给出 public static AnnotationDemo1 operator +(AnnotationDemo1 AnnotationDemo1) if( AnnotationDemo1.m_PrizeLevel=PrizeLevel.champion) throw new Exception(此示例等最高，已经不能再提升！); switch (AnnotationDemo1.m_PrizeLevel) case PrizeLevel.runner_up: AnnotationDemo1.m_PrizeLevel =PrizeLevel.champion; break; case PrizeLevel.third_place: AnnotationDemo1.m_PrizeLevel = PrizeLevel.runner_up; break; return AnnotationDemo1; / / 通过重载 + ，合并两个注释示例对象。 / / 1、如果两个注释示例对象的名子相同和创建时间都相同，则根据以下原则合并两个注释 / a、两个注释修改的时间超过30天，则按最近的日期的为最正确的注释内容的进行修改，并修改修改注释的时间； / b、若条件 a 不成立，则按 PrizeLevel奖品级别最高的为最正确的注释内容进行修改，并修改修改注释的时间； / c、若以上条件均不成立，则以异常的形式提示修改注释示例失败； / / 注释示例对象1 / 注释示例对象1 / 当不符合合并注释示例的规则时，错误提升信息提示以异常的方式给出 / 返回合并两个注释示例是否成功；true 表示全并两个注释示例成功； false 此方法不/会返回false,当合并不成功时直接产生错误; public static bool operator +(AnnotationDemo1 AnnotationDemo1, AnnotationDemo1 AnnotationDemo2) if (AnnotationDemo1.m_DemoName = AnnotationDemo2.m_DemoName & System.Math.Abs(AnnotationDemo1.LastChangedDate.Subtract(AnnotationDemo2.LastChangedDate).TotalDays) 30)/两个注释修改的时间超过30天 if (AnnotationDemo1.LastChangedDate.Subtract(AnnotationDemo2.LastChangedDate).TotalDays 0)/判断那一个的日期早 AnnotationDemo2.m_DemoContent = AnnotationDemo1.m_DemoContent; AnnotationDemo1.LastChangedDate = DateTime.Now; return true; else AnnotationDemo1.m_DemoContent = AnnotationDemo2.m_DemoContent; AnnotationDemo2.LastChangedDate = DateTime.Now; return true; else if (int)(AnnotationDemo1.m_PrizeLevel) (int)(AnnotationDemo1.m_PrizeLevel) AnnotationDemo1.m_DemoContent = AnnotationDemo2.m_DemoContent; AnnotationDemo1.LastChangedDate = DateTime.Now; return true; else throw new Exception(合并两个注释示例失败，没有符合规则的标准，请手动合并！); / / 根据合并两个注释示例对象 / / 注释示例1 / 注释示例2 / 合并的注释示例不符合规则 public void CombinationAnnotationDemo(AnnotationDemo1 AnnotationDemo1, AnnotationDemo1 AnnotationDemo2) bool m_IsCombinationed= AnnotationDemo1 + AnnotationDemo2; / / 提高注释示例的级别 / / 注释示例1 public void raiseLevel(AnnotationDemo1 AnnotationDemo1) AnnotationDemo1+; / / 奖品级别 / public enum PrizeLevel / / 冠军 / champion, / / 亚军 / runner_up, / / 季军 / third_place / / 文件路径结构 / public struct FilePathStruct / / 文件名 / string FileName; / / 文件路径 / string FilePath; / / 注释 / public interface IA