软件编码规范模板.docx

《软件编码规范模板.docx》由会员分享，可在线阅读，更多相关《软件编码规范模板.docx（20页珍藏版）》请在taowenge.com淘文阁网|工程机械CAD图纸|机械工程制图|CAD装配图下载|SolidWorks_CaTia_CAD_UG_PROE_设计图分享下载上搜索。

1、1.简介本规范为一套编写高效可靠的C#代码的标准、约定和指南。它以安全可 靠的软件工程原则为基础，使代码易于理解、维护和增强，提高生产效率。同时， 将带来更大的一致性，使软件开发团队的效率明显提高。2 .适用范围本规范适用于公司所有的C#源代码，为详细设计，代码编写和代码审核提 供参考和依据。3 .代码组织与风格3.1. Tab要使一个Tab为4个空格长。3.2. 缩进要使一个代码块内的代码都统一缩进一个Tab长度。3.3. 空行建议适当的增加空行，来增加代码的可读性。在在类，接口以及彼此之间要有两行空行：在下列情况之间要有一行空行：方法之间；局部变量和它后边的语句之间；方法内的功能逻辑部分之

2、间；3.4. 函数长度每个函数有效代码（不包括注释和空行）长度不要超过50行。4 .注释4.1. 注释的基本约定注释应该增加代码的清晰度；保持注释的简洁，不是任何代码都需要注释 的，过多的注释反而会影响代码的可读性。注释不要包括其他的特殊字符。建议public static int Green = l;public static int Blue = 2;好的写法public enum Color(Red,Green,Blue)不要把枚举用于开放的场合，例如操作系统的版本，朋友的名字等；枚举最后一个值不要加逗号；枚举中不要提供为了今后使用而保留的枚举值；9.成员设计规范方法，属性，事件，构造函

3、数以及字段等统称为成员。9.1. 成员设计的一般规范9.2. 方法的重载规范；避免在重载中随意的给参数命名。如果两个重载中的某个参数表示相同的输 入，那么该参数的名字应该相同。例如：public class String(好的写法public int IndexOf(string value) .public int IndexOf(string value, int startindex) 不好的写法public int IndexOf(string value) public int IndexOf(string strz int startindex) )避免使重载成员的参数顺序不一致。

4、在所有的重载中，同名参数应该出现在 相同的位置。例如：public class EventLog(public EventLogO;public EventLog(string logName);public EventLog(string logName, string machineName);public EventLog(string logName, string machineName, string source);)较短的重载应该仅仅调用较长的来实现。另外，重载如果需要扩展性，把最 长重载做成虚函数。例如：public class String(public int Index

5、Of(string s)调用return IndexOf(s, 0);public int IndexOf(string s, int startindex)调用return IndexOf(s, startindex, s.Length);)public virtual int IndexOf(string s, int startindex, int Count)(实际的代码)要允许可选参选为nullo这样做是为了避免调用者调用之前需要检查参数是否null0例如：允许为null时的调用DrawGeometry(brush, pen, geometry);不允许为null时的调用if (ge

6、ometry = null) DrawGeometry(brush, pen);else DrawGeometry(brush, pen, geometry);9.3. 属性和方法的选择基本原则是方法表示操作，属性表示数据。如果其他各方面都一样，优先使 用属性而不是方法。要使用属性，如果该成员表示类型的逻辑attribue如果属性的值存储在内存中，而提供属性的目的仅仅是为了访问该值，要使 用属性而不要使用方法如果该操作每次返回的结果不同，那么要使用方法。例如来自于met framework的例子：/好的写法Guid.NewGuid();不好的写法DateTime.Now;如果该操作比访问字段慢

7、一个或多个数量级，要使用方法。如果该操作有严重的副作用，要使用方法。9.4. 属性的设计规范：如果不应该让调用方法改变属性值，要创建只读属性；不要提供只写属性；要为所有的属性提供合理的默认值，这样可以确保默认值不会导致漏洞或效 率低的代码；要允许用户以任何顺序来设置属性的值；避免在属性的获取方法抛出异常。属性的获取方法应该是个简单的操作,不应该有任何的条件。如果一个获取 方法会抛出异常，按么可能它更应该设计为方法。9.5. 构造函数的设计规范建议提供简单的构造函数，最好是默认构造函数。简单的构造函数增强易用 性；考虑扩展性，如果构造函数设计的不自然，建议用静态的工厂方法来替代构 造函数；要把构

8、造函数的参数用作设置主要属性的便捷方法。如果构造函数参数仅用 来设置属性，应和属性名称相同。仅有大小写的区别；要在构造函数中做最少的工作。任何其他处理应该推迟到需要的时候；要在类中显示的声明公用的默认构造函数，如果这样的构造函数是必须的。如果没有显示默认构造函数，填加有参数构造函数时往往会破坏已有使用默 认构造函数的代码；避免在对象的构造函数内部调用虚成员。这样在扩展设计的时候会导致难以 理解的现象；9.6. 字段设计规范不要提供公有的或受保护的字段。代之以属性来访问字段；要只用常量字段来表示永远不会改变的量。否则会导致兼容性问题。下面是 正确的例子：public const int MaxV

9、alue = 0x7fffffff;public const int MinValue = unchecked(int)0x80000000);)要用公有的静态只读字段来定义预定义的对象实例。例如：public struct Color (public static readonly Color Red = new Color(OxOOOOFF);)9.7. 参数的设计规范要用类结构层次中最接近基类类型来作为参数的类型，同时要保证该类型能 够提供成员所需的功能。例如：要设计一个集合遍历的方法，那么参数应该是lEnbumerable为参数，而 不应该是IList,这样方法具有更强的适应性。不要使

10、用保留参数。如果将来需要更多的参数，那么可以增加重载成员。例 如：不好的写法public void Method(string reserved, SomeOption option);/好的写法public void Method(SomeOption option);将来填加public void Method(SomeOption option, string path);9.7.1. 参数设计中枚举和布尔参数的选择规范要用枚举。在代码阅读，书写中，枚举都比布尔的可读性好很多。例如：使用布尔型，阅读的时候不会轻易了解参数的含义FileStream f = File.Open( l.txt

11、 , true, false);使用枚举型FileStream f = File.Open( l.txt , CasingOptions.CaseSenstive,FileMode.Open);不要使用布尔参数，除非百分之百肯定绝对不需要两个以上的值。即使此时, 采用枚举往往也可以提供更好的可读性，如上例。考虑在构造函数中，对确实只有两种状态值的参数以及用来初始化布尔属性 的参数使用布尔类型；9.7.2. 参数验证的规范：要验证传给公有的，受保护的或显示成员的参数是否合法。如果验证失败, 应该抛出 System.ArgutmentException 或其子类;要抛出System.Argutme

12、ntNullException ,如果传入的null ,而该成员 不支持null ;9.7.3. 参数传递的规范：避免使用输出参数或引用参数；9.8. 展性设计规范如果没有恰当理由，不要把类密封起来。这些理由包括：A）类为静态类；B）类的受保护成员保存了高度机密信息；C）类继承了许多虚成员，逐个密封的代价太高，不如密封整个类；D）不要在密封类中声明保护成员或虚成员，因为无法覆盖其实现；建议用保护成员用于高级定制。它提供了扩展性，同时也避免了公用接口过 于复杂；不要使用虚成员，除非有合适的理由；建议只有在绝对必须的时候才用虚成员提供扩展性，并使用Template Method模式；要优先使用受保

13、护的虚成员，而不是公有虚成员。公有成员通用调用受保护 的虚成员的方式来提供扩展性；9.9. 常处理规范异常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏 的数据，资源耗尽，等等。通常的法则是系统在正常状态下以及无重载和硬件失 效状态下，不应产生任何异常。异常处理时可以采用适当的日志机制来报告异常,括异常发生的时刻；一般情况下不要使用异常实现来控制程序流程结构;使用异常而不要用错误代码来报告错误；要通过抛出异常的方式来报告操作失败。如果成员无法成功地完成它应该做任务，那么应该抛出异常;11.1. 异常类型选择规范优先考虑使优先考虑使System命名空间中已有的异常，而不是自己创建

14、新的异常类型；要使用最合理，最具针对性的异常。例如，对参数为空，应抛出System.ArgutmentNullException ,而不是System.ArgutmentException11.2. 异常处理规范不是百分之百确定的情况，不要吞掉异常；建议捕获特定类型的异常，如果理解该异常在具体环境当中产生的原因；不要捕获不应该捕获的异常，通常应该允许异常沿着调用栈传递；进行清理工作时要用try-finally ,避免使用try-catch ;要在捕获并重新抛出异常时使用空的throw语句，这是保持调用栈的最好 方法113.标准异常类的使用：1.1. .1. Exception与System E

15、xception不要抛出这两种类型的异常；避免捕获这两种异常，除非是在顶层的异常处理器中；1.2. InvalidOperationException对象处于不正确状态时抛出；11.3.3. ArgumentException , ArgumentNullException ,ArgumentOutOfRangeException如果传入的是无效参数，要抛出参数异常，尽可能使用位于继承层次末尾的 类型；要在抛出异常时设置ParaName属性；11.3.4. NullRefernceException , IndexOutOfRangeException , AccessViolationExc

16、eption不要显示抛出或捕获；11.3.5. StackOverflowException :不要显示抛出或捕获；1.1.6. . OutOfMemoryException :不要显示抛出或捕获；11.4. 自定义异常类型设计规则：避免太深的继承层次；要从已有的异常基类继承；异常类要以Exception做为后缀；要使异常可序列化，使其能跨应用程序域和远程边界仍能正常使用；要把与安全性有关的信息保存在私有的异常状态中11.5. 异常与性能如果在普通场景都会抛出异常，要采用先效验合法性的方式来避免抛出异常 引起的性能问题；12.其他规定 先写注释，后写代码，注释和代码一起完成如果语句块（比如循环

17、和条件分枝的 代码块）代码太长，嵌套太多，则在其结束要加上注释，标志对应的开始 语句如果分支条件逻辑比较复杂，也要加上注释。4.2. 注释类型4.2.1. 块注释主要用来描述文件，类，方法，算法等，放在所描述对象的前边。具体格式 以IDE编辑器输入7自动生成的格式为准，另外再附加我们自定义的格式，如下所列：/Remark作者，创建日期，修改日期/ Remark 对类 和接口的注释必须加上上述标记，对方法可以视情况考虑4.2.2. 行注释主要用在方法内部，对代码，变量，流程等进行说明。整个注释占据一行。4.2.3. 尾随注释与行注释功能相似，放在代码的同行，但是要与代码之间有足够的空间，便 于分

18、清。例：int m = 4 ; /注释如果一个程序块内有多个尾随注释，每个注释 的缩进要保持一致。4.3. 程序修改注释新增代码行的前后要有注释行说明，对具体格式不作要求，但必须包含作者, 新增时间，新增目的。在新增代码的最后必须加上结束标志；删除代码行的前 后要用注释行说明，删除代码用注释原有代码的方法。注释方法和内容同新增；为避免频繁改动代码，代码中只写比较简单的和不会经常发生变化的SQL。在VS开发环境中，采用代码分析工具来做自动化的代码分析，以保证代 码质量。13.参考文档1 ,.NET设计规范删除的代码行建议用析egion XXX #endregion代码段折叠，保持代码文件干 净整

19、洁修改代码行建议以删除代码行后再新增代码行的方式进行（针对别人的代 码进行修改时，必须标明，对于自己的代码进行修改时，酌情进行）。5.命名5.1. 命名的基本约定要使用可以准确说明变量/字段/类的完整的英文描述符，如firstNameo对作用显而易见的变量可以采用简单的命名，如在循环里的递增（减）变量就 可以被命名为i 。要尽量采用项目所涉及领域的术语。要采用大小写混合， 提高名字的可读性。为区分一个标识符中的多个单词，把标识符中的每个单词的 首字母大写。不采用下划线作分隔字符的写法。有两种适合的书写方法，适应于 不同类型的标识符：PasalCasing :标识符的第一个单词的字母大写； ca

20、melCasing :标识符的第一个单词的字母小写。避免使用缩写,如果一定要 使用，就谨慎使用。同时，应该保留一个标准缩写的列表，并且在使用时保持一 致。对常见缩略词，两个字母的缩写要采用统一大小写的方式（示例：ioStream , getlOStream ）;多字母缩写采用首字母大写，其他字母小写的方式（示例： getHtmITag ）;避免使用长名字（最好不超过15个字母）。避免使用相似或者仅在大小 写上有区别的名字。5.2. 各种标示符类型的命名约定5.2.1. 程序集命名公司域名（Physiomedtec ） +项目名称+模块名称（可选）5.2.2. 命名空间命名采用和程序集命名相同的

21、方式：公司域名(Physiomedtec )+项目名称+ 模块名称。另外，一般情况下建议命名空间和目录结构相同。5.2.3. 类和接口命名类的名字要用名词；避免使用单词的缩写，除非它的缩写已经广为人知，如 HTTP0接口的名字要以字母I开头。保证对接口的标准实现名字只相差一个T 前缀，例如对IComponent的标准实现为Component;泛型类型参数的命名: 命名要为T或者以T开头的描述性名字，对同一项目的不同命名空间中的类, 命名避免重复。避免引用时的冲突和混淆；5.2.4. 方法命名第一个单词一般是动词如果方法返回一个成员变量的值，方法名一般为Get+成员变量名，如若返 回的值是boo

22、l变量，一般以Is作为前缀。另外，如果必要，考虑用属性来 替代方法，如果方法修改一个成员变量的值，方法名一般为：Set +成员变量名。 同上，考虑用属性来替代方法；5.2.5. 变量命名按照使用范围来分，我们代码中的变量的基本上有以下几种类型，类的公有 变量;类的私有变量(受保护同公有)；方法的参数变量；方法内部使用的局部变 量。这些变量的命名规则基本相同，见标识符大小写对照表。区别如下：i .类的公有变量按通常的方式命名，无特殊要求；ii .类的私有变量采用两种方式均可：采用加m前缀，例如 mWorkerName;iii .方法的参数变量采用camalString，例如workerName

23、;iv .方法内部的局部变量采用camalString，例如workerName ;不要用_或&作为第一个字母；尽量要使用短而且具有意义的单词；单字符的变量名一般只用于生命期非常短暂的变量。一般用于integer; c,d,e 一般用于characters ; s用于string如果变量是集合. 则变量名要用复数。6 .声明每行要只有一个声明，如果是声明i,j,k之类的简单变量可以放在一行；除 了 for循环外，声明要放在块的最开始部分。for循环中的变量声明可以放在 for语句中。如：for(int i = 0; I 10; i +)。避免块内部的变量与它外部的变 量名相同。7 .表达式和语

24、句每行建议只有一条语句。if-elsejf-elseif语句，任何情况下,都应该有格式如下:if condition)statements,else if (conditiori)statement)else(statement)for语句格式如下：for (initialization, condition, update(statements,)如果语句为空：for initialization condition, update ;while语句格式如下：while (conditiori)statements,如果语句为空：while (conc/t/on);dONhIe 语句格式如下

25、:dostatements.)while condition)switch语句，每个switch里都应包含default子语句格式如下:switch condition)case ABC:statements,/* falls through */case DEF:statements,break;case XYZ:statements,break;default:statementbreak;)try-catch语句格式如下：try(statement)catch (Exceptionclass e)(statements,)finally(statements;)8 .类型设计规范要确保每

26、个类型由一组定义明确，相互关联的成员组成，而不仅仅是一些无 关功能的随机集合；8.1. 类型和命名空间要用命名空间把类型组织成相关域的层次结构。避免过深的命名空间；避免太多的命名空间；8.2. 类型和接口的选择要优先采用类而不是接口。接口的缺点在于语义变化时改变困难。注意接口并不是协定，把协定和实现 分开并非一定用接口实现，用基类和抽象类同样可以表达；建议使用抽象类而不是接口来解除协定与实现间的偶合；要定义接口，来实现类似多重继承的效果；精心定义接口的标志是一个接口只做一件事情。关键是接口的协定需要保持 不变，如果一个接口包含太多功能，那么这个胖接口产生变化的机会就会大得多。8.3. 抽象类设

27、计：不要在抽象类中定义公有的或内部受保护的构造函数。因为抽象类无法实例 化，所以这种设计会误导用户；要为抽象类定义受保护的构造函数或内部构造函数；8.4. 静态类设计静态类是一个只包含静态成员的类，它提供了一种纯面向对象设计和简单性 之间的一个权衡，广泛用来提供类似于全局变量或一些通用功能。要少用静态类。静态类应该仅用作辅助类；避免把静态类当作杂物箱。每个静态类都应该有其明确目的；不要在静态类中声明或覆盖实例成员；8.5. 枚举设计要用枚举来加强那些表示值的集合的参数，属性以及返回值的类型性；要优先使用枚举而不是静态常量。例如：不好的写法public static class Colorpublic static int Red = 0;