应用软件开发编码规范

2.1源程序有效注释量必须在20%左右。说明：注释的原则是有助于对程序的阅读理解，注释不宜太多 也不能太少，注释语言必须准确、易懂、简洁。 2.2包的注释内容：简述本包的作用、详细描述本包的内容、产品模块名称和版本、公司版权。说明： 在详细描述中应该说明这个包的作用以及在整个项目中的位置。 2.3文件注释：文件注释写入文件头部，包名之前的位置。说明：注意以/*开始避免被JavaDoc收 集。文件注释内容：版权说明、描述信息、生成日期、修改历史。 2.4类和接口的注释：该注释放在package关键字之后，class或者interface关键字之前。说明 方便JavaDoc收集。

应用软件开发编码规范

排水管道标准规范范本8公有和保护方法注释内容：列出方法的一句话功能简述、功能详细描述、输入参数、输出参娄 值、违例等。

例: /** *《一句话功能简述） *《功能详细描述》 *【参数]] [参数1说明] *【参数2] [参数2说明] *【返回类型说明] *【违例类型］【违例说明］ *【类、类#方法、类#成员］ */ 2.9对于方法内部用throw语句抛出的异常，必须在方法的注释中标明，对于所调用的其他方法所抛出 的异常，选择主要的在注释中说明。对于非RuntimeException，即throws子句声明会抛出的异常， 必须在方法的注释中标明。 2.10注释应与其描述的代码相近，对代码的注释应放在其上方或右方（对单条语句的注释）相邻位置， 不可放在下面，如放于上方则需与其上面的代码用空行隔开。 2.11注释与所描述内容进行同样的缩排。说明：可使程序排版整齐，并方便注释的阅读与理解。 例: public void example() //注释 CodeBlock One 飞江 //注释 CodeBlock Two 2.12将注释与其上面的代码用空行隔开。 例： //注释 program code one //注释 program code two 2.13对变量的定义和分支语句（条件分支、循环语句等）必须编写注释。说明：这些语句往往是程序 实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计 文档。 2.14对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处 理，必须在该case语句处理完、下一个case语句前加上明确的注释。说明：这样比较清楚程序编写者

实现某一特定功能的关键，对于维护人员来说，良好的注释帮助更好的理解程序，有时甚至优于看设计 文档。 2.14对于switch语句下的case语句，如果因为特殊情况需要处理完一个case后进入下一个case处 理，必须在该case语句处理完、下一个case语句前加上明确的注释。说明：这样比较清楚程序编写者 的意图，有效防止无故遗漏break语句

应用软件开发编码规范

2.15边写代码边注释，修改代码同时修改相应的注释，以保证注释与代码的一致性。不再有用的注释 要删除。 2.16注释的内容要清楚、明了，含义准确，防止注释二义性。说明：错误的注释不但无益反而有害。 2.17避免在注释中使用缩写，特别是不常用缩写。说明：在使用缩写时或之前，应对缩写进行必要的 说明。

3.1包名采用域后缀倒置的加上自定义的包名，采用小写学母。在部门内部应该规划好包名的范围，防 止产生冲突。部门内部产品使用部门的名称加上模块名称。产品线的产品使用产品的名称加上模块的名 称。

应用软件开发编码规范

5属性名使用意义完整的英文描述：第一个单词的学母使用小写、剩余单词首学母天写其余学母 大小写混合法。属性名不能与方法名相同

数据类不能包含数据处理的逻辑。 通信类不能包含显示处理的逻辑

数据类不能包含数据处理的逻辑。

应用软件开发编码规范

4所有的数据类必须重载toString（方法，返回该类有意义的内容。说明：父类如果实现了比 的 toString ，子类可以继承不必再重写。

6异常捕获后，如果不对该异常进行处理，则应该纪录日志或者ex.printStackTraceO。说明 特殊原因必须用注释加以说明，

应用软件开发编码规范

4.7自己抛出的异常必须要填写详细的描述信息。说明：便于问题定位。 4.8运行期异常使用RuntimeException的子类来表示，不用在可能抛出异常的方法声明上加throws子 句。非运行期异常是从Exception继承而来，必须在方法声明上加throws子句。说明：非运行期异常 是由外界运行环境决定异常抛出条件的异常，例如文件操作，可能受权限、磁盘空间大小的影响而失败， 这种异常是程序本身无法避免的，需要调用者明确考虑该异常出现时该如何处理方法，因此非运行期异 常必须有throws子句标出，不标出或者调用者不捕获该类型异常都会导致编译失败，从而防止程序员 本身疏忽。运行期异常是程序在运行过程中本身考虑不周导致的异常，例如传入错误的参数等。抛出运 行期异常的目的是防止异常扩散，导致定位困难。因此在做异常体系设计时要根据错误的性质合理选择 自定义异常的继承关系。还有一种异常是Error继承而来的，这种异常由虚拟机自己维护，表示发生 了致命错误，程序无法继续运行例如内存不足。我们自已的程序不应该捕获这种异常，并且也不应该创 建该种类型的异常。 4.9在程序中使用异常处理还是使用错误返回码处理，根据是否有利于程序结构来确定，并且异常和错 误码不应该混合使用，推荐使用异常。说明：一个系统或者模块应该统一规划异常类型和返回码的含义。 但是不能用异常来做一般流程处理的方式，不要过多地使用异常，异常的处理效率比条件分支低，而且 异常的跳转流程难以预测。 4.10注意运算符的优先级，并用括号明确表达式的操作顺序，避免使用默认优先级。说明：防止阅读 程序时产生误解，防止因默认的优先级与设计思想不符而导致程序出错。 4.11避免使用不易理解的数字，用有意义的标识来替代。涉及物理状态或者含有物理意义的常量，不 应直接使用数字，必须用有意义的静态变量来代替

应用软件开发编码规范

12数组声明的时候使用int[」index，而不要使用intindex[」。说明：使用intindex[ 程序的可读性较差

例： 如下程序可读性差： public int getIndexO[] 如下程序可读性好： public int[J getIndex 13调试代码的时候，不要使用System.out和System.err进行打印，应该使用一个包含统一开关 测试类进行统一打印。说明：代码发布的时候可以统一关闭调试代码，定位问题的时候又可以打开开 14用调测开关来切换软件的DEBUG版和正式版，而不要同时存在正式版本和DEBUG版本的不同源文 ，以减少维护的难度。

应用软件开发编码规范

行库（CLR）支持区分大小写和不区分大小写的语言

1.3标识符的大小写规则

1.4首字母缩写词的大小写规则

首字母缩写词是由术语或短语中各单词的首字母构成的单词。例如，HTML是HypertextMarkup Language 的首字母缩写。只有在公众广为认知和理解的情况下，才应在标识符中使用首字母缩写词。 首字母缩写词不同于缩写词，因为缩写词是一个单词的缩写。例如，ID是identifier的缩写。通常情 况下，库名不应使用缩写词。 首字母缩写词的大小写取决于首字母缩写词的长度。所有首字母缩写词应至少包含两个字符。为了 便于这些准则的实施，如果某一首字母缩写词恰好包含两个字符，则将其视为短型首字母缩写词。包含 三个或三个以上字符的首字母缩写词为长型首字母缩写词。 下列准则为短型和长型首字母缩写词指定了正确的大小写规则。标识符大小写规则优先于首字母缩 写词大小写规则。 a）两字符首字母缩写词的两个字符都要大写，但当首字母缩写词作为大小写混合格式的标识符的 首个单词时例外。例如，名为DBRate的属性是一个采用Pascal大小写格式的标识符，它使用 短型首字母缩写词(DB)作为首个单词。又如，名为ioChannel的参数是一个采用大小写混合格 式的标识符，它使用短型首字母缩写词（10）作为首个单词。

应用软件开发编码规范

b）包含三个或三个以上字符的首字母缩写词只有第一个字符大写，但当首字母缩写词作为大小写 混合格式的标识符的首个单词时例外。例如，名为XmlWriter的类是一个采用Pascal大小写 格式的标识符，它使用长型首字母缩写词作为首个单词。又如，名为htmlReader的参数是 个采用大小写混合格式的标识符，它使用长型首字母缩写词作为首个单词。 C 如果任何首字母缩写词位于采用大小写混合格式的标识符开头，则无论该首字母缩写词的长度 如何，都不大写其中的任何字符。例如，名为xmlStream的参数是一个采用大小写混合格式的 标识符，它使用长型首字母缩写词（xml)作为首个单词。又如，名为dbServerName的参数是 个采用大小写混合格式的标识符，它使用短型首字母缩写词（db）作为首个单词。

1.5首字母缩写词的大小写规则

不要将所谓的紧凑格式复合词中的每个单词都大写。这种复合词是指写作一个单词的复合词，如 “endpoint"。 例如，hashtable是一个紧凑格式的复合词，应将其视为一个单词并相应地确定大小写。如果采用 Pascal大小写格式，则该复合词为Hashtable：如果采用大小写混合格式，则该复合词为hashtable。 若要确定某个单词是否是紧格式的复合词，请查阅最新的词典 下表列出了不是紧凑格式复合词的一些常用术语。术语先以Pascal大小写格式显示，后面的括号 容 中的是其大小写混合格式。 a) BitFlag (bitFlag) b) FileName(fileName) c) Logoff(1logoff) d) LogOn(1ogOn) e) SignIn (signIn) f) SignOut (signOut) g) UserName (userName) h WhiteSpace (whiteSpace)

通用命名约定讨论的是如何为库元素选择最适当的名称。这些准则适用于所有标识符。后面各节讨 论特定元素（如命名空间或属性）的命名。 a) 可读性比简洁性更重要。属性名称CanScrollHorizontally比ScrollableX（指X轴，但意 义不明确）更好。 b) 不要使用下划线、连学符或任何其他非字母数字学符。 c) 不要使用匈牙利表示法。匈牙利表示法是在标识符中使用一个前缀对参数的某些元数据进行编 码，如标识符的数据类型。 d)i 避免使用与常用编程语言的关键字冲突的标识符。虽然符合CLS的语言必须提供将关键字用

应用软件开发编码规范

作普通字的方法，最佳做法不要求强制开发人员了解如何实现。 对于大多数编程语言，语言参 考文档都会提供语言所使用的关键字列表。

1.7程序集和DLL的名称

例如，System.Net.Sockets命名 间包含的类型允许开发人员使用套接字通过网络进行通信。命名空间名称的一般格式如下： .(|)[.][.] 例如，Microsoft.WindowsMobile.Direct a) 使用公司名称作为命名空间的前缀以防止不同公司开发的命名空间具有相同的名称和前缀。 b）在命名空间名称的第二级使用稳定的、与版本无关的产品名称。 c) 不要根据组织层次结构确定命名空间层次结构中的名称，因为公司的部门名称经过一段时间后 可能会改变。命名空间名称是长期使用的、不会更改的标识符。组织的不断发展和变化不应使 命名空间名称过时 d) 使用Pascal大小写格式，并用句点分隔命名空间各部分（如Microsoft.Office.PowerPoint） 如果您的品牌采用了非传统的大小写，应遵循您的品牌所定义的大小写，即使它与常用的命名 空间大小写相背离也如是。 适当的时候可考虑使用复数命名空间名称。例如，使用System.Collections而不使用 e System.Collection。但是，品牌名称和首字母缩写词属于此规则的例外情况。例如，使用 System.I0，而不要使用System.10s。 命名空间和其中的类型不要使用相同的名称。例如，不要在将“Debug”用作命名空间名称的 同时，又在该命名空间中提供一个名为“Debug”的类。有些编译器要求对这种类型进行完全 限定。

1.9类、结构和接口的名称

通常，类型名称应该是名词短语，其中名词是由类型表示的实体。例如，Button、Stack和Fi 有名称，用于标识由类型表示的实体。从开发人员的角度选择标识实体的名称：名称应反映使用场

应用软件开发编码规范

准则中提及的从某个其他类型继承的类型，指的是所有的继承者，而不只是直接继承的类型。例如， 从Exception继承的类型添加Exception后缀”这一准则意味着在继承层次结构中具有 otion的任何类型都应该使用以Exception结尾的名称。每条这样的准则还用来保留指定的后缀； 类型满足该准则表述的条件，否则不应使用该后缀。例如，如果类型不是从Exception直接或间 承的，则类型名称不能以Exception结尾。 a）按照Pascal大小写格式，使用名词或名词短语（或偶尔使用形容词短语）为类、接口和值类 型命名。 2 不要为类名加前缀（如字母C)。 考虑在派生类的末尾使用基类名称。 d）为接口名称加上字母I前缀，以指示该类型为接口。 在定义类/接口对（其中类是接口的标准实现）时，一定要确保类和接口的名称除接口名称以 字母I为前缀外，二者应完全相同。例如，Framework提供IAsyncResult接口和 AsyncResult类。 用描述性名称为泛型类型参数命名，除非单个字母的名称已完全可以自我说明而无需描述性名 称。IDictionary是一个符合此准则的接口的示例 ）对具有一个单字母类型参数的类型，考虑将字母T用作这些类型的类型参数名称。 h）将字母T作为描述性类型参数名称的前缀 i）考虑在参数名称中指示置于类型参数上的约束。例如，约束于ISession的参数可称为 TSession。 j）向自定义属性类添加Attribute后缀。ObsoleteAttribute和AttributeUsageAttribute是 符合此准则的类型名称。 向在事件中使用的类型（如C#事件的返回类型）的名称添加EventHandler后缀 AssemblyLoadEventHandler是符合此准则的委托名称。 向不是事件处理程序的委托的名称添加Cal1back后缀。 不要向委托添加 Delegate 后缀。 向扩展System.EventArgs的类添加EventArgs后缀。 不要从System.Enum类派生；使用当前所用语言支持的关键字。例如，在C#中应使用enun 关键字 向从System.Exception继承的类型添加Exception后缀。 向从System.I0.Stream继承的类型添加Stream后缀。 System.Security.CodeAccessPermission继承的类型或实现System.Security.IPermission 的类型添加Permission后缀。 s）不要在枚举值名称中使用前缀。例如，不要对ADO枚举使用ad之类的前缀，也不要对多格 式文本枚举使用rtf之类的前缀，依此类推。 不要将Enum用作枚举类型的后缀

应用软件开发编码规范

不要在标志枚举的名称中添加Flags作为后缀。 对枚举使用单数名称，除非枚举值是位域。 w）对使用位域值的枚举（也称为标志枚举）使用复数名称。

1.10类型成员的名称

选择适当的参数名称可极大改善库的可用性。适当的参数名称应指示该参数会影响的数据或功能 a）对参数名称使用Camel大小写。 b）使用描述性参数名称。在大多数情况下，参数名称及其类型应足以确定参数的用法

应用软件开发编码规范

a）在资源键中使用Pascal大小写格式。 b) 提供描述性标识符，而不要提供短标识符。尽量保持标识符的简洁性，但不要牺牲可读性。 c) 不要使用公共语言运行库（CLR）编程语言中特定于语言的关键字 d) 在命名资源中只能使用字母数字字符和下划线。 e) 使用点分隔符（“.”）以清晰的层次结构表示标识符。 f) 对异常消息资源使用下面的命名约定。资源标识符应由异常类型名称加上异常的短标识符构成 二者之间以点分隔。例如，ArgumentException。 g）BadEnumValue符合此准则

具有特殊格式的注释可用于指导某个工具根据这些注释和它们后面的源代码元素生成XML。这 是以三个斜杠（///）开始的单行注释，或者是以一个斜杠和两个星号（/**）开始的分隔注释。 释后面必须紧跟它们所注释的用户定义类型（如类、委托或接口）或者成员（如字段、事件、属

应用软件开发编码规范

b）cref属性可以附加到任意标记，以提供对代码元素的参考。文档生成器必须验证此代码元素 是否存在。如果验证失败，文档生成器将发出警告。查找在cref属性中描述的名称时，文档 生成器必须根据源代码中出现的using语句来考虑命名空间的可见性。 C