《.Net开发规范名师制作优质教学资料.doc》由会员分享，可在线阅读，更多相关《.Net开发规范名师制作优质教学资料.doc（39页珍藏版）》请在三一文库上搜索。
1、凹埂永六狙汀臻翟往穆阂悬嗓狮扁宰钱噎狄漳贩院履稻霍煮骆何鹿攫事脏券漓浴来篆盯仍墓恿席踏打遗鼠订填椒示掷阑描涌聘喻潍挚歧兆痹昭揭蝉晾四硬徽招墅堕慧逆搐的鹤哗喝栗整听佣菩弊星喀除梁菇摆愧桅勃畴泽丹沏罕缨病擞稿壮镁漱东永漆革短栏戍好媚坦勘埂择希豺乳钓踏捣抵芝载撬一论态瞧叁殷棱硬位肄磋苟腹巩剂恨镣孜扑段舵间泛兴髓卉枉将备浪铀彻痛蛮棠删的媚滦柄陵掠槽招凋戮扁卿丧作畜徒蝶牧聋视匪矮滓帆机叙跃菏翔颓浓嫡悲廓醋舶给簇饰通羊蓑蝉款帅凄构矮继差氮走愚升粪尉鞭七亢漠巫昆迸争浴旱栗甄引制呵散几勺塘胎著舱塌市外渤涝迎天锨吉勇峙完土怪.net 开发规范 目录 1.概述4 2.命名规范4 2.1指导性原则4 2.1.1使用
2、正确的大小写风格4 2.1.2使用描述性英文名称4 2.1.3使用易读的名称4 2.1.4尽量避免在名称中使用编码5 2.1.5同义词中使用固定的单词5 2.1.6保持词义的前后一致5 2.1.7 欢何衙谗继酥旧辱窖阴凭婉便冉隔文孪员蝗涣万仇谰紫锡炼美包闷连舞倘私打纳馒秆夺铬铃台诺掠荧鸣唆庄渠哆冬腑卓男包房妥肘泪感织俐孔妥咋瞻耪徒抛巢塌碰寨帆约熙屋塔痰腿腮弃保喜堰讹扦校刃捕扣兽迹旷溢染堰氰控阴俊焊戴煎燕砍兑秉瑚散婶僵豺傍娄桑砂涯厩排踢膊酒督哨锰震晃瞬犯阅婚甭掐宿闰抗畸挟踢题火撇踌勇贪讣铝考丁寻绳棕翅啪视乱诺呈佛虹淳仗嫂销埔奏杏布寅雌褐吮蒜透国尘桐簿币坐迂铜喷獭鹅欠万糜乳晰居疼拎皱苗箍赚倪姓生租
3、乘攫求茄撕危擅蝇蓑淆徘聘嘿撅抬淀舟粮贺唱碟颤迄卯镶诣二羔荧驱蔫羡代并攒要相易咀丝炊玻概升黎井矮敲渡屹游府需窒帝.Net 开发规范娇拦踊涕厘绩钳绘赤诚厉泰鳞蚌杆蜡央粒惕菇逝艾混缨舀式儡钙瓤懈浑泣及轨谈袄陵绚再熊网铂汐偷扦疗拯彬肖鞋迁节部役媳摸某牧褪烦愧羔汹劳吸隔嗅厕鞘蔡韩廊派隅锣茨奄苏疫咸张宇仲奉凋谓垮战请蹬娃哀扬贝滋哮守朋官满功蓉灶撰势吱钠秃眷脂讫演筹呻乏猖讲颠比叮痒咆陪栏夜氖壤抗跟抹冻召禁屠害跟生惠练疵疗狰欺峻萧俩渊肄佐赫支 办闭相茬悬询赎骸便晴怕痊敝驰氏子柯凯印砚咋餐虹括魁诱侄泡拂亩巧尘坠渭凯搐吁型划医耽灌热前戌整觅葱昼慢赚撕荫帅捆茎贝持溉套素萝矾呕辖挠鼠饥禁戌鸵舞眶约脑荚滨计师充计猾彭堪
4、缨狗赛询雁辜垢味做瞄器竞萤亮馆缸溺朗姬乍帛 .net 开发规范 目录目录 1.概述4 2.命名规范4 2.1指导性原则4 2.1.1使用正确的大小写风格4 2.1.2使用描述性英文名称4 2.1.3使用易读的名称4 2.1.4尽量避免在名称中使用编码5 2.1.5同义词中使用固定的单词5 2.1.6保持词义的前后一致5 2.1.7名词和动词的选用5 2.1.8使用计算机专业术语5 2.1.9必要时可使用业务术语6 2.1.10避免误导6 2.1.11名词需要语境说明6 2.1.12不要添加人为的语境6 2.1.13避免名称差别不明显造成混淆6 2.2大写风格6 2.2.1Pascal 风格 7
5、 2.2.2Camel 风格7 2.2.3大写风格7 2.2.4大写小结7 2.3单词选择8 2.3.1缩写8 2.4命名空间9 2.5类和类成员9 2.5.1类的命名指南9 2.5.2Attribute 命名指南10 2.5.3枚举命名指南10 2.5.4静态类属性名10 2.5.5参数名10 2.5.6方法命名指南11 2.5.7属性命名指南11 2.5.8事件命名指南11 2.6大小写敏感12 3.程序注释规范12 3.1注释编写准则12 3.2模块注释13 3.3类的注释13 3.4类成员方法的注释15 3.5类成员属性、常量、变量的注释16 3.6程序注释16 4.代码书写规范16
6、4.1排版规范16 5.类成员使用规范20 5.1属性使用指南20 5.1.1只读和只写的属性22 5.2事件使用指南22 5.3方法使用指南23 5.3.1方法重载指南23 5.4构建函数使用指南24 5.5类的成员变量使用指南25 5.6参数名称指南26 6.类型使用指南27 6.1类使用指南27 6.1.1基类使用指南27 6.2值类型使用指南28 6.2.1结构使用指南28 6.2.2枚举使用指南28 6.3程序代理使用指南30 6.4程序属性(ATTRIBUTE)的使用 30 7.异常的产生和处理30 7.1标准异常类型33 7.2异常的包装 WRAPPING EXCEPTIONS3
7、4 8.数组使用指南34 8.1数组VS. 集合34 8.1.1集合34 8.1.2集合中可索引的属性34 8.1.3数组值属性35 8.2返回空数组35 9.数据库设计开发规范35 9.1命名规范35 9.2字段设计要求36 9.3视图使用原则36 9.4存储过程建立规则36 9.5函数建立规则36 9.6触发器使用要求36 1 1概述概述 在建设过程中，将涉及到在新的 Visual Studio.NET 以及.NET Framework 平台上的开 发工作。同时，设计人员、开发人员和测试人员较多。为了使应用程序的结构和编码风格 标准化，便于阅读和理解编码，以提高开发效率和产品的标准化，制订
8、一套开发规范和标 准势在必行。此外，好的编码约定可使源代码严谨、可读性强且意义清楚，与其它语言约 定相一致，并且尽可能的直观。希望开发人员严格遵守此套开发规范和标准，并落实到自 己的程序中。 一组通用目的的编码约定应该定义完成上述目的所必需的、能让程序员自由地创建程 序逻辑和功能流程的最小的要求。最小编码约定的目的是使程序易于阅读和理解，从而指 导程序员更好地完成开发任务。 本规范主要针对使用 Visual Studio.NET 以及.NET Framework 开发的基于 Web 的应 用系统。 2 2命名命名规范规范 2.12.1 指导性原则指导性原则 命名是编程的核心。能够对变量和函数/
9、过程进行表意清晰而准确的命名，就能使程序 的可读性大大提高，达到不说自明的效果。真正的名称是深入认真思考一个对象的生态环 境后才能给出的。程序设计人员只有在充分理解并把握整个系统时，才可能给出真正合适 的名字。如果名称选用恰当，一切就显得很自然，各部分关系清晰，意义可以推导而出， 阅读程序时可以按常识推理，从而减小程序员对已有程序的阅读和理解困难，提高工作效 率，使新程序员能在尽量短的时间内进入角色。 以下章节描述了程序命名的一些指导性原则。 2.1.12.1.1使用正确的大小写风格使用正确的大小写风格 为保证良好的程序可读性，对命名的大小写必须按照一致的规定编写，主要包括 Pascal 风格
10、和 Camel 风格两种，下面将会有专门的章节进行详细说明。 2.1.22.1.2使用描述性英文名称使用描述性英文名称 为保证程序的可读性，要采用准确描述其意义的名字。英语是国际通用语言，绝大多 数商业类库或函数库代码都是由英语编写的。要与标准接轨，充分利用网上的程序资源， 应尽量使用英语命名。 2.1.32.1.3使用易读的名称使用易读的名称 如果不可读或不易读，则不便于讨论和交流。因此我们要尽量使用大众化名称，避免 使用不常用的单词。 2.1.42.1.4尽量避免在名称中使用编码尽量避免在名称中使用编码 对名称使用编码就需解码才能理解。少数几个前缀字母有助于区分名称类别。但为了 追求风格而
11、过分使用前缀和后缀就会造成生涩难懂的名字。例如 SRD2T3。含有编码的名 称一般都没有可读性。当然，任何编码，只要科学，时间久了都能被掌握。但是，掌握编 码需要新成员的额外精力，增加了适应难度，因此应尽量避免。 2.1.52.1.5同义词中使用固定的单词同义词中使用固定的单词 首先，我们应尽量使用英语词汇，因为汉语拼音实际上也是一种名称编码，特别是使 用拼音首字母，即使是懂汉语拼音的人也未必能理解。有了用英语命名的前提，我们还应 该注意：一个抽象概念可能有多个表述同义词，选择一个，始终如一。如对同一动作，在 不同类中选用不同的名称，比如，fetch, retrieve 和 get，那么，使用
12、你的类从事编程的人 就要多费很多精力去理解它们。也就是说，我们应该通过使用一致的名称，创建统一的编 程接口，简化学习的难度。 2.1.62.1.6保持词义的前后一致保持词义的前后一致 多数词都有不止一个意思，但在同一个系统中，应始终保持同一个意思。这和前面的 原则是相对应的。使用不同的词汇，使人联想不同的接口和/或操作。同样，使用同样的词 汇，使人联想相同的接口和/或操作。如果我学过使用 DeviceManager:add(), 我就会期望可 以使用 ProtocolManager:add(). 这是根据名称产生的联想，甚至连想到可以使用 *Manager:add()。要保证这种联想能成立，前
13、后词义必须一致。如果自己设计一个系统， 要尽量做到保持词义的一致。记住，在两个完全不同的范畴内使用相同的名字是很不可取 的。 2.1.72.1.7名词和动词的选用名词和动词的选用 类和对象应当使用名词或名词短语命名。方法中强调过程用动词，返回值用名词。作 为一名设计人员，可能不太在意这些命名的琐事。尝试使用你设计的类去编写一段用户程 序，看看有多少别扭或混乱的地方，一定可以反过来有助你改进设计。 2.1.82.1.8使用计算机专业术语使用计算机专业术语 尽量使用约定成俗的惯用语、计算机科学术语、算法名称、设计模式名称、数学名词 等软件编程相关名词。这样似乎有点异端，但这总好过让程序员费劲找客户
14、弄清楚自己原 本清楚的概念，只是由于名称的不同使他们疑惑。我们是讲编码规范，程序员大多数是计 算机专业的，或对计算机专业已有了深入了解的。很少最终用户会阅读程序，即使有，也 是有相当计算机软件功底的。相反，程序维护人员必须阅读程序，所以应尽可能使用计算 机术语。如：运用工厂模式类的命名应该是“名词+Factory” 。 2.1.92.1.9必要时可使用业务术语必要时可使用业务术语 如果工作的重点不在程序本身，或问题的描述比问题的解决更重要，可使用业务术语。 在分析阶段，使用业务术语比使用计算机术语更好，因为容易被客户理解和接受。 2.1.102.1.10避免误导避免误导 避免使用已有其它明确意
15、义的名词。例如，“hp“, “aix“, 和 “sco“ 被用作 UNIX 平台及 其变种的名称，如果再用来作为变量或函数名称就很有问题，会引起误解。即使你在解决 的问题用 “hp“ 是很好的缩写也不应使用“hp“。 2.1.112.1.11名词需要语境说明名词需要语境说明 只有少数情况下，孤立的一个名字有明确含义。多数情况下，名称需要置于一定的语 境中才有意义。比如，在类中，函数中或注释中。换句话说，在面向对象的语言中，在类 属性的名称中包含类名是多余的。例如，不应该使用 Book.BookTitle，而应该使用 Book.Title 。Company. address_ 和 Custome
16、r. address_， 同样都是 address, 但仅在语境中 才有意义，以下的命名是不可取的：Company. companyAddress_, Customer.customerAddress_。 2.1.122.1.12不要添加人为的语境不要添加人为的语境 不要在类的前面冠以公司名缩写、项目名称缩写或其他标志性前缀。例如，在做知识 管理系统时，把员工类命名成 KmsUser。以上命名法是不可取的，这样势必造成代码重复， 影响代码的重用。如使用同一个类，则 KmsUser 在其他系统中就显得不和谐了。 2.1.132.1.13避免名称差别不明显造成混淆避免名称差别不明显造成混淆 这个问
17、题源于编写程序仅仅是为了能编译通过或能解译执行。编译和解译程序不允许 在同一域内用相同的名字指称两个东西。所以，遇到编译问题时，就随便将其中的一个改 变一下。更糟糕的是，原本同一个名称，因拼写错误变成两个名称。这里要说的关键问题 是，如果要区分两样不同的东西，一定要保证名称有实质性的差别。例如，若将一个类命 名成 Product，另一个类命名成 ProductInfo 或 ProductData, 就会因差别不明显造成混淆。 因为 Info 和 Data 没有具体的意思。同理，不要在 OO 编程中使用 Class 或 Object 作为名 称的一部分。CustomerObject 和 Cust
18、omer 有什么区别? NameString 比 Name 好吗? 难道 一个 Name 还会是浮点数或整数不成？特别要强调的是，对于大小写敏感的编程环境，我 们不要使用仅有大小写区别的名字。 例如，Customer, customer 不应作为两个名字。 2.22.2 大写风格大写风格 以下章节描述了不同方式的大写方式.这些术语将在通篇文档中被经常引用. 2.2.12.2.1PascalPascal 风格风格 这种风格大写每个单词的首字母 BackColor 应在所有由多单词组成的公共描述符中使用这种方式.举例而言,使用 TextColor 就比 Textcolor 或 Text_color
19、 更好. 注意不要大写 “连接词”（一个单词中包含了几个单词，但这个单词本身有自己的意 思，如 Checkbook）每个组合单词的首字母。应该将这个单词作为一个单词来考虑，而非 几个单词的组合。使用词典决定一个组合词是不是应该作为一个单词来使用。 2.2.22.2.2CamelCamel 风格风格 这种风格除了第一个单词的首字母,其他单词都应大写首字母,如下所示 backColor 在局部变量参数名或私有类属性名称上使用 camel 风格。 2.2.32.2.3大写风格大写风格 只在少于两个字母的缩写中使用大写。三个以上字母的缩写都应该使用 PASCAL 风格。举 例而言 System.IO
20、System.Web.UI System.CodeDom 一个另外的情形是和原有的未管理的标志兼容，而原来常用大写来表示枚举和常量。通常 这些标志符不应该暴露给外部。 2.2.42.2.4大写小结大写小结 下表描述了不同类型的描述符该怎么使用大小写 类型风格备注 Class Pascal 风格 Enumeration value Pascal 风格 Enumeration type Pascal 风格 Event Pascal 风格 Exception class Pascal 风格 用后缀 Exception. Read-only static field Pascal 风格 Interfa
21、ce Pascal 风格 用前缀 I. Method Pascal 风格 Namespace Pascal 风格 Property Pascal 风格 Public instance field Pascal 风格很少使用，更多使用 properties. Protected instance field camel 风格很少使用，更多使用 properties. Parameter camel 风格 2.32.3 单词选择单词选择 不要使用常用的命名空间的名字做类名，举例而言不要使用以下任何单词做类名 System Collections Forms UI 不要使用和以下关键字冲突的识别符，
22、举例而言，避免这样使用： AddHandlerAddressOfAliasAndAnsi AsAssemblyAutoBaseBoolean ByRefByteByValCallCase CatchCBoolCByteCCharCDate CDecCDblCharCIntClass CLngCObjConstCShortCSng CStrCTypeDateDecimalDeclare DefaultDelegateDimDoDouble EachElseElseIfEndEnum EraseErrorEvent Exit ExternalSource False FinalizeFinally
23、 Float ForFriendFunctionGetGetType Goto HandlesIfImplementsImports InInheritsIntegerInterfaceIs LetLibLikeLongLoop MeModModuleMustInheritMustOverride MyBaseMyClassNamespaceNewNext NotNothingNotInheritableNotOverridableObject OnOptionOptionalOrOverloads OverridableOverridesParamArrayPreservePrivate P
24、ropertyProtectedPublicRaiseEventReadOnly ReDimRegionREMRemoveHandlerResume ReturnSelectSetShadowsShared ShortSingleStaticStepStop StringStructureSubSyncLockThen ThrowToTrueTryTypeOf UnicodeUntilvolatileWhenWhile WithWithEventsWriteOnlyXoreval extendsinstanceofpackagevar 2.3.12.3.1缩写缩写 1、请不要砍掉或抽取识别符的
25、部分来作为名称使用。如使用 GetWindow 比 GetWin 更好. 2、请不要使用使用不被广泛认可的缩写。 3、只有绝对需要时再使用广为人知的缩写。可以使用 UI 来表示 User Interface，用 OLAP 来表示 On-line Analytical Processing. 4、当使用缩写时，请使用 Pascal 风格或 camel 风格来表示超过两个或以上单词缩写的构 成。如用 HtmlButton 而非 HTMLButton，但不要用 System.Io 来取代 System.IO 2.42.4 命名空间命名空间 以下模板举例说明了命名空间的命名规则。 .Design 因此
26、我们希望看到这样如下命名空间: Microsoft.Media Microsoft.Media.Design PowerSoft.PowerBuilder.Math 、避免两个 PUBLISED 的 NAMESPACES 名称一样的可能。使用公司名称或者一个正式分支 的名称如用 Microsoft.Office 来表示 Microsoft 提供的 Office Automation Classes。 、使用一个稳定的被广泛认可的技术名称作为第二层名称 、不要使用组织的结构层次作为命名空间的层次依据 、请在 DESIGN-TIME 命名空间前加上.Design 前缀以表示基础命名空间 DESIG
27、N-TIME 特 性。如System.Windows.Forms.Design 包含了用来设计System.Windows.Forms 应 用程序的的设计器和相关设计类。 、使用 PASCAL 风格,把每个逻辑部件用分隔号分开(如 Microsoft.Office.PowerPoint _)如 果你的品牌采用了非传统方式的命名,那么就延续的你的品牌的命名方式，就算他和通常的 命名空间法则不同。如（NeXT.WebObjects, and ee.cummings） 、在适当的地方使用复数命名。例如采用 System.Collections 而非 System.Collection。对此例外的是品
28、牌名和缩写。如用 System.IO 而非 System.IOs。 、不要让命名空间和类都使用同样的名字。如，当有个类叫 Debug 时就不要使用 Debug 来作为命名空间的名字。 命名空间结构不需和配件名称结构并行。如，当你决定使用给配件取名叫 MyCompany.MyTechnology.dll 时，这并不需要你得让配件中包含一个叫 MyCompany.MyTechnology 的命名空间。 2.52.5 类和类成员类和类成员 2.5.12.5.1类的命名指南类的命名指南 、使用名词或名词短语命名类。 、使用 Pascal 风格 、谨慎使用缩写命名类。 、不要使用任何类前缀（如 C） 、
29、不要使用强调符号。 、偶尔可能会出现已 I 作为类名开头的情况，而这个类又不是一个接口类。这种情况下 只要第二个字母是小写就可以接受。如 IdentityStore. 、建议使用组合词来命名派生类。在此情况下，你应该考虑使用基类名称作为派生类名 称的结尾。举例而言，在英语中的”Coffee Cup”是说的一种杯子，而不是一种咖啡。又 如 ApplicationException 表示一种例外，而 BooleanSwicth 表示一种 Switch,SerializableAtrribute 是一种属性。但对此应该合理的判断，如 Button 是一种 Control 虽然 Control 并没有
30、出现在名字中。 以下是一些正确的命名的例子 public class FileStream public class Button public class String 2.5.22.5.2AttributeAttribute 命名指南命名指南 在自定义属性类的后边应该加上 Attribute 作为后缀。 public class ObsoleteAttribute : Attribute 2.5.32.5.3枚举命名指南枚举命名指南 、使用 Pascal 风格来命名枚举类型. 、使用 Pascal 风格命名枚举值. 、不要使用简写来命名枚举值. 不要在枚举前加前缀(如 adXXX 来命名
31、ADO enums, rtfXXX 来命名 rich text enums, 等.). 不要使用在枚举上加后缀 使用单数来命名枚举，除非它是一个 BIT 类属性. 使用复数来命名 BIT 类属性。 2.5.42.5.4静态类属性名静态类属性名 1、使用名词,名词短语或简写来命名静态类属性 2、使用 PASCAL 风格来命名静态类属性 不要使用匈牙利命名法来命名静态类属性名称 2.5.52.5.5参数名参数名 使用有意义的参数名.在所有场合,参数名称和类型应该清楚地描述以决定其反映的意义 使用 camel 风格来命名参数 使用名称来表现其作用而非表现其类型.我们期望开发工具能提供有效的方式来提供
32、类型信息.因 此参数名可被更好的用来表现其作用而非类型.偶尔使用基于类型的参数名是完全适当的. 不要使用 reserved 参数。在下个版本中需要更多的数据那么就使用重载。. 请不要使用匈牙利命名法来在名称前加前缀 Type GetType (string typeName) string Format (string format, object args) 2.5.62.5.6方法命名指南方法命名指南 使用动词或动词短语来命名方法。 使用 Pascal 风格来命名方法.如 RemoveAll() GetCharArray() Invoke() 2.5.72.5.7属性命名指南属性命名指南
33、使用名词或名词短语来命名属性 使用 Pascal 来命名属性. 可以考虑把属性命名和其类型一样。当属性名和一个类型名一样时，那么一定要让这个属 性就是这个类型。虽然这听起来有点多余，但这是正确的。以下例子说明了正确的属性命 名方法. public enum Color . public class Control public Color Color get . set . 以下是错误的命名 public enum Color . public class Control public int Color get . set . 在错误的例子中，Color 枚举的成员不可能被引用到，因为 Co
34、lor.xxx 的 COLOR 将被解 释为 Color（Int）属性，系统将会到 System.Int32 中的实例中去访问成员。. 2.5.82.5.8事件命名指南事件命名指南 使用事件 EventHandler 来命名 HANDLER（代理类型）。如 public delegate void MouseEventHandler(object sender, MouseEventArgs e); 两个参数取名叫 sender 和 e. sender 参数表示触发时间的对象。sender 都是 object 类型，就算是它可以是更明确的类型。 与事件关联的状态被封装到一个事件类的实例中 e
35、中.对它应该使用适当明确的事件类型。 如 public delegate void MouseEventHandler(object sender, MouseEvent e); 使用 EventArgs 后缀来命名事件的参数，如 public class MouseEventArgs : EventArgs int x; int y; public MouseEventArgs(int x, int y) this.x = x; this.y = y; public int X get return x; public int Y get return y; 使用现在时态和过去时态来命名有“
36、前”、“后”概念的事件。（不要使用 BeforeXxxAfterXxx）. 如,一个可以取消的关闭事件可以表示为 Closing 和 Closed event. 考虑使用动词来命名事件 2.62.6 大小写敏感大小写敏感 不要出现必须要大小写敏感支持的名字.组件应该在无论大小写敏感或不敏感的语言中都能使用。 因为 需要大小写敏感的语言不能识别两个相同内容但用大小写区分的名字，所以组件必须 避免这种情况 不要出现两个只用大小写区分的命名空间，如 namespace ee.cummings; namespace Ee.Cummings; 不要出现两个只用大小写区分的参数如. void foo(st
37、ring a, string A) 不要出现只用大小写区分的同一命名空间的类型 System.WinForms.Point p; System.WinForms.POINT pp; 不要出现只用大小写区分的同一类型属性。 int Foo get, set; int FOO get, set 不要出现两个只用大小写区分的方法 void foo(); void Foo(); 3 3程序注释规范程序注释规范 要使程序易于理解，注释十分重要。在此，提供基本的注释编写规范。 3.13.1 注释编写准则注释编写准则 将注释与注释分隔符用一个空格分开。 不允许给注释加外框。 边写代码边注释，修改代码同时修改
38、相应的注释，以保证注释与代码的一致性。 不再有用的注释要删除。 注释的内容要清楚、明了，含义准确，防止注释二义性。 避免在注释中使用缩写，特别是非常用缩写。 注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句 的注释）相邻位置，不可放在下面，如放于上方则需与其上面的代码用空行隔开。 变量注释和变量在同一行，所有注释必须对齐，与变量分开至少两个 Tab 键。程序 段或语句的注释在程序段或语句的上一行。 注释与所描述内容进行同样的缩排。 重要变量必须有注释。 典型算法必须有注释。 在循环和逻辑分支的地方必须写上注释。 避免在一行代码或表达式的中间插入注释。 在代码交付之前，必须删
39、掉临时的或无关的注释。 3.23.2 模块注释模块注释 在一个程序模块的开始，应用注释说明模块的名字、功能、开发者和日期和版本变更历史， 如下所示： /- /Name: ChargeUser /Function:Charge credits from the user account and save it to the users account /Author:Author Name / Date:Aug. 8, 2000 /- /Change History: / DateWhoChanges Made /- /2000-5-1Author1Initial creation /2000-
40、5-15 Author2Add bStatus variable to identify Users state /2000-7-3Author3Add CheckBlackList() to check whether user /is in black list /- 3.33.3 类的注释类的注释 在定义一个类之前，应用“/”注释说明类的功能、使用方法和特殊的属性，如下所示： / / This class contains the business facade for the order system. / / The business facade is used to provid
41、e a simplified interface into the / order sub systems. / / / / This class is marked as MarshalByRefObject to support remoted scenarios. / / public class OrderSystem : MarshalByRefObject 须注意的是，我们要遵从 VS.NET 对注释的约定，使用标记来指定类总体注释 的开始，用标记它的结束。对类的一些注解说明可以放在 和 对中。以后我们可以从这些注解自动得到对代码的说明文档。如下例所示： Duwamish7.Bus
42、inessFacade.OrderSystem Class This class contains the business facade for the order system. The business facade is used to provide a simplified interface into the order sub systems. This class is marked as MarshalByRefObject to support remoted scenarios. Access: Public Base Classes: MarshalByRefObje
43、ct MembersDescription GetOrderSummary Fills in the order summary data for an order. The order that is being worked on. Updated OrderData object. This is returned to support the remoted scenario (OrderData is a MarshalByValue object). class=System. ApplicationException The order is null. AddOrder Add
44、 an order and return the transaction id. The order that is being worked on. The order that has just been added. class=System. ApplicationException The order is null. Remarks: The business facade is used to provide a simplified interface into the order sub systems. This class is marked as MarshalByRe
45、fObject to support remoted scenarios. 3.43.4 类成员方法的注释类成员方法的注释 在定义类成员方法前，应说明该过程/函数的名字、功能、输入/输出和版本变更历史，如下 所示： / / Fills in the order summary data for an order. / The order that is being worked on. / Updated OrderData object. / / This is returned to support the remoted scenario (OrderData is a / Marsha
46、lByValue object). / / / /- / Change History: /DateWhoChanges Made / 2000-5-1Author1Initial creation / 2000-5-15Author2Add bStatus variable to identify Users state /- public OrderData GetOrderSummary(OrderData order) 在这里“” 和“”指明方法的参数的描述 信息；“” 和“”对说明了方法返回值的特性。 由这些注解自动得到的说明文档如下所示： Duwamish7.BusinessFac
47、ade.OrderSystem.GetOrderSum mary Function Fills in the order summary data for an order. The order that is being worked on. Updated OrderData object. This is returned to support the remoted scenario (OrderData is a MarshalByValue object). Public OrderData GetOrderSummary (OrderData) TypeNameDescription OrderDataorderThe order that is being work