美邦.软件开发规范.doc

美特斯邦威-软件研发部 2009-7-13美邦.软件开发规范概述11) 排版22) 注释23）命名技巧43.1过程43.2变量43.3常量63.4接口（Interface）命名规范63.5其它63.6 类型前缀73.7控件类型命名前缀74) 编程约束95) 用户界面145.1概述145.2总体规范145.3 人机交互窗口设计规范145.3.1易用性原则145.3.2安全性原则155.2.3合理性原则155.3.4美观与协调性原则176) 总则17概述编码标准应该始终贯穿代码生产的各个阶段，开发者应该严格遵守，以利于标准的执行。由开发团队完成的源代码应该表现出一致协调的风格。 在软件开发过程中，编程的工作量是相当大的，同一项目参与编程的人可能有各自编程的经验和习惯，不同风格的程序代码带来了维护工作量的增加，因此为了提高代码的可读性、系统的稳定性及维护和升级的成本，程序的代码必须严格遵循统一的编程规范。 总则： 应有良好的、尽可能一致的编程风格 编码应该是严谨的、可读性强、目标明确及直观的。 每一位开发人员或者外包工作人员必须严格执行下述标准：1) 排版l 编写程序时要采用缩进风格，缩进的空格数为4个。l 相对独立的程序块之间，变量说明之后必须加空行。l 较长的语句要分成多行书写，要在操作符处划分新行，操作符放在新行行首，划分出的新行要进行适当的缩进，增强可读性。l 除了特殊的IF语句外，多个短语句不能写在一行中，每行写一句。l 如果函数或过程的参数较长，要进行适当的划分。l 循环、判断等语句中如果有较长的表达式或语句，要进行适当的划分。l 只使用空格键，不要使用TAB键。l 函数或过程的开始、循环或判断等语句中的代码都要采用缩进风格，case语句下的分支语句也要采用缩进。l 为了防止在阅读代码时不得不滚动源代码编辑器，每行代码或注释在1024*800的显示频率下不得超过一显示屏l 当一行被分为几行时，通过将串联运算符放在每一行的末尾而不是开头，清楚地表示没有后面的行是不完整的。l 每一行上放置的语句避免超过一条。l 在大多数运算符之前和之后使用空格，这样做时不会改变代码的意图却可以使代码容易阅读。例：int j = i + k; 而不应写为 int j=i+k;l 将大的复杂代码节分为较小的、易于理解的模块。l 编写 SQL 语句时，对于关键字使用全部大写，对于数据库元素（如表、列和视图）使用大小写混合。 将每个主要的 SQL 子句放在不同的行上，这样更容易阅读和编辑语句，例如： SELECT FirstName, LastNameFROM CustomersWHERE State = WA2) 注释软件文档可以分为两种形式，外部文档和内部文档。外部文档是与源代码分开的，比如说明书、帮助文档和设计文档。内部文档主要包括开发人员开发时写在源代码里的注释。外部文档应该包括使用说明、设计报告、变换需求、bug修复历程，以及所使用的编码标准。即使有了外部文档，源代码清单也应该独立，因为这些外部文档可能会丢失。 不要给注释添上一个花哨的外框，这看起来很吸引人，但不容易维护。代码交付使用之前，删掉临时的或无关的注释，避免在将来维护工作中引起混淆。如果你需要给一段复杂代码注释，最好重新审视你的代码，然后决定要不要重写。有可能的话，与其给不好的代码注释，不如重新编写。尽管不要为了让别人使用方便而牺牲性能，但是在性能和可维护性之间必须找到一个平衡点。注释时尽可能使用完整的句子，注释应该让代码变得清晰，而不是变得更加含糊。编码的同时就应该写注释，因为大多数情形下，以后就没时间做这个工作。而且，即使你有机会重新阅读你的代码，然而今天看起来很显然的东西，六个星期以后就不再那么清楚明白了。l 避免使用多余的或不相称的注释，比如幽默的评论。l 使用注释说明代码的意图，而不是简单地翻译代码。l 对代码中任何不是很显然的内容进行注释。l 为了防止再出问题，通常在bug修复的地方写上注释，这对于团队开发尤为重要。l 在循环和逻辑分支的地方写上注释，因为这些地方对于阅读源代码的人来说是关键的区域。l 将注释与注释分隔符用空白分开，这样有利于让注释显得突出，特别是在没有颜色提示下更容易找到。l 在整个应用程序中，采用统一风格的注释，包括一致的标点符号和结构。/ /模块编号： /作用： /作者：作者中文名 /编写日期： /如果模块有修改，则每次修改必须添加以下注释： / /Log编号： /修改描述： /作者：修改者中文名 /修改日期： / 每个模块级变量必须给出注释 重要的变量应该给出注释描述变量的用途编码标准应该始终贯穿代码生成的各个阶段，开发者应该严格遵守，以利于标准的执行。由开发团队完成的源代码应该表现出一致协调的风格，提交的代码就像是由同一个程序员写出的。 在软件开发过程中，编程的工作量是相当大的，同一项目参与编程的人可能有各自编程的经验和习惯，不同风格的程序代码带来了维护工作量的增加，因此为了提高代码的可读性、系统的稳定性及维护和升级的成本，程序的代码必须严格遵循统一的编程规范。 总则： 应有良好的、尽可能一致的编程风格 编码应该是严谨的、可读性强、目标明确及直观的。 注释： 无论是用户端表示层程序还是组件程序，注释必不可少。要求能占程序总量的30%，另外注释必须在程序改变时实时更新。做到边修改代码边修改注释，对于修改别人的代码，要通知本人和项目管理员，得到同意后才进行修改，同时要在代码中写明修改的原因。3）命名技巧 理解应用的逻辑流（源程序），最好的帮助也许就是应用程序中各个不同元素的名字。名字应该说明“是什么”，而不是“怎样做”。避免使用记载内部实现信息的名字，因为这些实现有可能会改变。比如，你可以使用getNetxtStudent（），而不是getNextArrayElement（）。使用单词缩写来减小名字组合带来的复杂性。命名的一个原则是：当你在选择一个合适的名字时遇到困难，这就表明你需要进一步分析或定义该元素的用途。应该让名字尽可能长，使之具有确定的含义，但也应该昼短，避免过分冗长。从开发角度看，富于表现力的名字有助于提高代码的可读性。因此，名字最好能够让读者易于理解。然而，除此之外一定要确保你所选择的名字是遵循编程语言的规则和标准的。3.1过程避免使用易混淆的名字，比如将一个过程命名为analyze（），一个变量为XXK8。这样的名字带来的更多是含糊，而不是简洁。面向对象语言中，在类的属性中包括类名是多余的，比如book。bookTitle，应该改用book。Title。采用“动词名词”方法为基于指定对象执行某种操作的过程命名，比如calculateInvoiceTotal（）。在允许函数重载的编程语言中，所有的重载应该执行类似的功能。对于那些不允许函数重载的语言，制定一个命名标准将相似的函数联系起来。3.2变量如果需要，最好在变量名末尾附加上计算限定词，如Avg、Sum、Min、Max、Index等。在变量名中使用通常成双成对的反义词，如min/max、begin/end，和open/close等。由于大多数名字是连接好几个单词形成的，最好采用混合大小写格式以利于阅读，比如将连接的几个单词首字母大写。另外，为了有助于区分变量和过程，采用Pascal casing方法为过程和类命名，每个单词的首字母都大写，如CalculateInvoiceTotal；采用camel casing方法为变量命名，除了第一个单词，其它单词的首字母都大写，如documentFormatType。布尔型变量名应该包括Is，暗示Yes/No或True/False的值，如fileIsFound。给状态变量命名时，避免使用Flag这样的词。状态变量与布尔型变量不同，因为它们可能有多于两种可能的值。采用一个更具有描述性的名字较好，比如使用documentFormatType, 而不使用documentFlag。即使是对于可能只出现在几行代码中、生命期非常短的变量，我们仍然要使用一个有明确含义的名字。仅仅对于短循环才采用单字母，如I或j作为循环计数器。如果使用Charles Simonyi的匈牙利命名法，或其它的派系，最好为项目建立一套标准的前缀，这样有利于开发人员一致地命名变量。有时在变量名中包含表示该变量作用范围的符号十分有用，比如给全局变量加上g前缀，给模块级变量加上m前缀。程序中变量名称 = 变量的前缀 +代表变量含意的英文单词或单词缩写。1 类模块级的变量请用“_”作前缀public class Hello private string _Name; private DateTime _Date;2 类的属性所对应的变量，采用属性名前加“_”前缀的形式public class Hello private string _Name; public string Name get return mName;3 过程级的变量不使用前缀public class Hello void say() string SayWord;4 过程的参数使用小写作为开头 public class Hello void say(string sayWord) 补充说明： 针对异常捕获过程中的Exception变量命名，在没有冲突的情况下，统一命名为e；如果有冲突的情况下，可以重复e，比如：ee。Try /your code try/codecatch(Exception ee)/your codecatch(Exception e) /your code补充：如果捕获异常不需要作任何处理，则不需要定义Exception实例例：try /your codecatch( Exception )3.3常量常量都应该大写，单词之间用下划线连接，如 NUM_DAYS_IN_WEEK。另外在枚举类型的变量前加上公共的前缀，比如FONT_ARIAL和 FONT_ROMAN。3.4接口（Interface）命名规范 和类命名规范相同，唯一区别是 接口在名字前加上“I”前缀 例： interface IDBCommand; interface IButton;3.5其它尽量少使用缩写词，如果使用了某一个缩写，那么就应该在以后的使用中保持一致。一个缩写只能表示一个含义，反过来每一个被缩写的单词只能有一个缩写。比如，使用min作为minimum的缩写。给函数命名时，最好将返回值的描述包含进去，比如getCurrentWindowName（）。文件和目录名，也应该和过程名一样，应该切实描述清楚它们是做什么用的。避免对不同的元素重复使用同一个名字，比如，将一个程序命名为ProcessSales（）的同时，又将一个变量命名为processSales。命名元素时避免使用同音异义词，这样可以防止与别人讨论代码进引起的混淆，比如write和right。命名元素时避免使用容易拼错的单词，而且还要注意美国英语和英国英语之间的区别，比如color/colour和check/cheque。避免使用特殊字符来标识数据类型，比如用$代表字符串，用%代表整数。3.6 类型前缀数据类型前缀例子BooleanbbFoundBytebtbtRasterDateCurrencycrcrBalanceDatedtdtBeginDateDoubleddFeeDecimaldcdcFeeIntegeriiQtyLongllVcIDSinglesgsgAverageStringssItemIdObjectooRmtsvrDatasetdsdsItemDataTabledtdtOrderDataRowdrdrManDataRowCollectiondrsdrsManDataColumndcdcFieldDataColumnCollectiondcsdcsFieldVariantvvCheck自定义类型取有意思的2-4位小写开头udUserInfo 3.7控件类型命名前缀控件类型前缀例子Check boxchkchkReadOnlybuttonbutbutcmdExitCommon dialogdlgdlgFileOpencomboboxdbcbodbcboLanguageDataGridgrdgrdQueryResultListBoxlstlstJobTypeDirectory list boxdirDirSourceDrive list boxdrvDrvTargetFile list boxfilFilSourceFormfrmfrmEntryFramefrafraLanguageGraphgragraRevenueHorizontal scroll barhsbhsbVolumeImageimgImgIconImage comboimgcboimgcboProductImageListilsIlsAllIconsLabellablabHelpMessageTextBoxtxttxtNameLinelinLinVerticalList boxlstlstPolicyCodesListViewlvtlvtHeadingsMenumnumnuFileOpenMonth viewmvwMvwPeriodMS ChartchchSalesbyRegionMS Flex gridmsgmsgClientsMS Tabmst mstFirstOption button optoptGenderPicture box picPicVGAProgressBar prgprgLoadFileRemote Data rdrdTitlesSlider sldsldScaleSpin spnspnPagesStatusBarstastaDateTimeSysInfo sysSysMonitorTabStrip tabtabOptionsText boxtxttxtLastNameTimertmrtmrAlarmToolbartlbtlbActionsTreeViewtrvtrvOrganizationUpDownupdupdDirectionVertical scroll barvsbysbRate4) 编程约束1. 避免将多个类放在一个文件里面。 2. 一个文件应该只有一个命名空间，避免将多个命名空间放在同一个文件里面。3. 一个文件最好不要超过500行的代码（不包括机器产生的代码）。4. 一个方法的代码长度最好不要超过25行。（在一个屏幕上能完整看到整个方法，避免为了满足规范故意把字体设置很小）5. 避免方法中有超过5个参数的情况。使用结构或类来传递多个参数。6. 每行代码不要超过80个字符。7. 尽量不要手工的修改机器产生的代码。a) 如果需要编辑机器产生的代码，编辑格式和风格要符合该编码标准。b) 机器生成的partial classes 尽可能要保留它。8. 避免利用注释解释显而易见的代码。a) 代码应该可以自解释。b)好的代码由可读的变量和方法命名因此不需要注释。9. 文档仅提供业务的假设、算法、见解等等. 10. 避免使用方法级的文档。a) 使用扩展的API文档说明之。b) 只有在该方法需要被其他的开发者使用的时候才使用方法级的注释。（在C#中就是/）11. 不要硬编码数字的值，总是使用构造函数设定其值。12. 只有是自然结构才能直接使用const，比如一个星期的天数。如：public const int DAYS_IN_WEEK = 7;否则尽量使用static readonly;对于象值类型不能直接写public static readonly 的，可以这样来实现：private static decimal _MAX_COUNT;public static decimal MAX_COUNTgetreturn _MAX_COUNT并在类的静态构造函数中初始该值。 13 对获取或传进来的对象要使用Assert 来检查；using System.Diagnostics; object GetObject() object obj = GetObject(); Debug.Assert(obj != null); 14 代码的每一行都应该通过白盒方式的测试。15 在捕获(catch)语句的抛出异常子句中(throw)，总是抛出原始异常维护原始错误的堆栈分配。同时要对异常进行相应的提升。（体看MB.BaseFrame 平台开发约束）catch(Exception exception) throw ; /和throw exception一样。 16 避免方法的返回值是错误代码。17 尽量避免定义自定义异常类。18 当需要定义自定义的异常时；a) 自定义异常要继承于ApplicationException。b) 提供自定义的序列化功能。19 避免在单个程序集里使用多个Main方法。20 只对外公布必要的操作，其他的则为internal。21 不能从一个绝对路径加载程序集；22 使应用程序集尽量为最小化代码(EXE客户程序)。使用类库来替换包含的商务逻辑。23 避免给枚举变量提供显式的值。（历史遗留需要存储在数据库中的时候除外,否则应该存储名称）/正确方法 public enum Color Red,Green,Blue /避免public enum Color Red = 1,Green = 2,Blue = 3 24. 避免指定特殊类型的枚举变量。（位运算除外）/避免 public enum Color : long Red,Green,Blue 25. 即使if语句只有一句，也要将if语句的内容用大括号扩起来。26. 避免在条件语句中调用返回bool值的函数。可以使用局部变量并检查这些局部变量。bool IsEverythingOK() /避免 if (IsEverythingOK () /替换方案 bool ok = IsEverythingOK(); if (ok) 27. 总是使用基于0开始的数组。28. 在循环中总是显式的初始化引用类型的数组。public class MyClass MyClass array = new MyClass100; for(int index = 0; index array.Length; index+) arrayindex = new MyClass(); 29. 不要提供public 和 protected的成员变量，使用属性代替他们。30. 避免在继承中使用new而使用override替换。31. 除非使用interop(COM+ 或其他的dll)代码否则不要使用不安全的代码(unsafe code)。32. 避免显示的转换，使用as操作符进行兼容类型的转换。Dog dog = new GermanShepherd(); GermanShepherd shepherd = dog as GermanShepherd; if (shepherd != null ) 33. 不要提供公共的事件成员变量，使用事件访问器替换这些变量。public class MySource private MyDelegate _SomeEvent ; public event MyDelegate SomeEvent add _SomeEvent += value; remove _SomeEvent -= value; 34. 总是使用接口。35. 避免一个接口中只有一个成员,尽量使每个接口中包含35个成员,接口中的成员不应该超过20个。36. 避免接口成员中包含事件。37. 避免使用抽象方法而使用接口替换。38. 在类层次中显示接口。39. 推荐使用显式的接口实现。40. 从不假设一个类型兼容一个接口。 SomeType obj1; IMyInterface obj2; /* 假设已有代码初始化过obj1，接下来 */ obj2 = obj1 as IMyInterface; if (obj2 != null) obj2.Method1(); else /处理错误 41. 最终提交版本时表现给最终用户的字符串不要使用硬编码而要使用资源文件替换之。42. 不要硬编码可能更改的基于配置的字符串，比如连接字符串。43. 当需要构建长的字符串的时候，使用StringBuilder不要使用string44. 避免在结构里面提供方法。a) 建议使用参数化构造函数b) 可以重裁操作符45. 总是要给静态变量提供静态构造函数。46. 除非在不完全的switch语句中否则不要使用goto语句。47. 在switch语句中总是要有default子句来显示信息(Assert)。int number = SomeMethod(); switch(number) case 1: Trace.WriteLine(Case 1:); break; case 2: Trace.WriteLine(Case 2:); break; default : Debug.Assert(false); break; 48 除非在构造函数中调用其他构造函数否则不要使用this指针。/ 正确使用this的例子 public class MyClass public MyClass(string message ) public MyClass() : this(hello) 49. 除非你想重写子类中存在名称冲突的成员或者调用基类的构造函数否则不要使用base来访问基类的成员。/ 正确使用base的例子public class Dog public Dog(string name) virtual public void Bark( int howLong) public class GermanShepherd : Dog public GermanShe pherd(string name): base (name) override public void Bark(int howLong) base .Bark(howLong); 50. 通常情况下避免有从System.Object转换来和由System.Object转换去的代码，而使用强制转换或者as操作符替换。class SomeClass /避免： class MyClass void SomeMethod(T t) object temp = t; SomeClass obj = (SomeClass)temp; / 正确： class MyClass where T : SomeClass void SomeMethod(T t) SomeClass obj = t; 51. 在一般情况下不要定影有限制符的接口。接口的限制级别通常可以用强类型来替换之。public class Customer /避免：public interface IList where T : Customer /正确：public interface ICustomerList : IList 52. 总是选择使用C#内置的数据结构。5) 用户界面5.1概述 在Windows 平台下开发，界面主要涉及的技术有VS、ASP、 HTML。B/S 结构中菜单将主要采用HTML 形式、复杂的输入输出界面将采用在HTML 页面中嵌入VS 的ActiveX 控件的方式实现。查询将采用ASP 方式实现。5.2总体规范 系统主页要求美观大方，登录后的页面能体现系统的总体功能框架。ASP 与VS 的ActiveX 控件的字体及色彩基调应该保持一致风格。5.3 人机交互窗口设计规范5.3.1易用性原则 控件的名称或标题最好使用用户熟悉的字眼，而且不能超过4 个字。 完成相同或相近功能的按妞用Frame 框起来，按钮要支持快捷方式。 完成同一功能或任务的元素在集中位置，减少鼠标移动的距离。 按TAB 键自动切换的顺序应该与界面上控件的排列顺序保持一致。 按回车键能自动进入TAB 顺序表示的下一控件的焦点状态（验证不通过除外）。 界面上首先要输入的和重要的信息控件应该是TAB 键顺序靠前而且在比较醒目的位置，使对应控件在一开始就获得焦点。 同一界面的控件数最好不要超过15 个，多于15 个可以考虑按功能或属性分类的多 个页面显示。 分页界面的页面间用Ctrl+Tab 的组合快捷键切换，顺序按重要程度和访问几率排列。 复选框和选项框按选择几率的高低先后排列，并且有默认的选项。 选项数为25 时可用选项框，选项数为220 时可用下拉框，大于20 时用小查询按 钮查询选择。 选项数不定且数量不多的情况选用下拉框。选项数固定且数量范围为25 的情况下根据界面的当前排列情况选择选项框或下拉框。 按“新增”或“修改”按妞后未存盘而是按“取消”按钮应使界面回到初始状态。 对显示有当前记录资料的界面按“新增”操作时，可以提示保留当前值新增和清屏 新增两种方式，也可以选择取消回到初始界面。 在新增和修改状态下关闭窗口或按退出按钮提示是否保存修改。5.3.2安全性原则n 可写的控件的值改变时应该提供输入验证，不合格后应该自动获得焦点。n 首要排除可能会使应用非正常终止的错误，如：除零运算等，死循环、长度超过数据n 库规定的长度、含有特殊字符等。n 应当注意排除无意的无效数据录入，如数值形态的控件要防止录入字符等。n 应该避免未授权功能的使用及无意义的操作。n 对可能引起致命错误或系统出错的输入字符和动作要加以限制和屏蔽。n 界面上操作数据库中关联性强的表时，如：一对一或多的表的关系时，存储动作应该n 放在一个按钮中完成。n 影响数据库操作的特殊字符，如： 、“、空格等要做特殊处理后再参与数据库操作。n 日期采用统一的YYYY/MM/DD 格式表示。而且日期的合理性必须得到验证。（若给n 大陆以外的客户使用，日期处理更加复杂）。n 小数点的位数必须根据数据库字段的要求加以限制。n 费率等数值不能录入负数值。n 对输入的字符串和数值数据必须限制长度不能超过数据库规定。n 界面能捕获ESC 键的使用，执行退出代码的功能。n 取消操作能回到初始状态。5.2.3合理性原则n ActiveX 控件应放在浏览器页面比较显眼的位置，能在浏览器常用工具栏显示的情况下，可以在一个屏幕中显示完整的ActiveX 控件界面，不需拉动滚动条。n 非法输入和操作应该有足够明确的提示说明，提示说明不能混淆和重复，如“不能输入大于600的数字”“数字应该小于或等于600”应该只保留其中一种说法。不能出现A处有A 的说法，B处有B 的说法，其实是一个意思。n 一些键盘或鼠标的屏蔽性的操作无须用MsgBox 来显示提示信息，如控件只能输入数字、小数点、“-”，当输入字符时不需要有任何提示。n 提示或警告信息必须具有向导性，能告知用户错误原因，并自动使需改变的控件在第一时间内获得焦点。n 按钮的排列应该遵循新增、修改、删除、打印、退出等主题的排列顺序。注意界面按钮的屏蔽逻辑，如按下“新增”后屏蔽新增、修改、删除按钮，在对应位置显示存盘、取消按钮等。整个系统应该采用统一的界面按钮逻辑风格。n 不需要另外界面输入打印查询条件的打印功能应该有预览和打印两个按钮。预览排在前面。n 删除的动作必须先有提示信息确认是否真正删除。n 如果执行的处理时间比较长（可能比较长）要有进度条或者等待界面提示用户等待系统响应。n 按钮必须提供快捷方式，快捷键的取值符合其它MIS 项目的共同习惯。 功能快捷键说明增加Ctrl+N增加一个新的内容明细保存Alt + A添加或保存一个明细资料（