软 件 开 发 编 码 规 范(C#)
目
录 1 引言 ......................................................................................................................................... 3 1.1 编写目的 .................................................................................................................. 3 1.2 背景 .......................................................................................................................... 3 1.3 定义 .......................................................................................................................... 3 1.4 参考资料 .................................................................................................................. 3 2 基本要求.................................................................................................................................. 3 2.1 程序结构要求 .......................................................................................................... 3 2.2 可读性要求 .............................................................................................................. 3 2.3 结构化要求 .............................................................................................................. 4 2.4 正确性与容错性要求 .............................................................................................. 4 2.5 可重用性要求 .......................................................................................................... 5 3 用户界面设计原则 .................................................................................................................. 5 4 源程序书写规范 ...................................................................................................................... 5 4.1 通用源代码格式规则 .............................................................................................. 5 4.1.1 缩进 .................................................................................................................. 5 4.1.2 边距 .................................................................................................................. 6 4.1.3 “{}”的使用 .................................................................................................... 6 4.1.4 注释 .................................................................................................................. 6 4.2 语句格式与语句书写规范 ...................................................................................... 6 4.2.1 括号 .................................................................................................................. 6 4.2.2 保留字和关键字 .............................................................................................. 7 4.2.3 函数 .................................................................................................................. 7 4.2.4 变量 .................................................................................................................. 7 4.2.5 语句 .................................................................................................................. 7 5 命名规范.................................................................................................................................. 9 5.1 函数命名 .................................................................................................................. 9 5.2 形参 .......................................................................................................................... 9 5.3 常量和变量 .............................................................................................................. 9 5.3.1 常量和宏定义 .................................................................................................. 9 5.3.2 变量 .................................................................................................................. 9 5.4 函数使用说明、接口命名、NameSpace 命名 .................................................... 10 5.5 控件的命名 ............................................................................................................ 11 5.6 类型 ........................................................................................................................ 11 5.6.1 一般类型 ........................................................................................................ 11 5.6.2 构造类型 ........................................................................................................ 12 5.6.3 类类型 ............................................................................................................ 12 5.7 文件和文件夹 ........................................................................................................ 12 5.7.1 文件夹的命名规则 ........................................................................................ 12 5.7.2 文件命名 ........................................................................................................ 13 6 源程序文档注释规范 ............................................................................................................ 13 6.1 注释文档的一般规范 ............................................................................................ 13
1 1 引言
1.1 编写目的
本规范旨在用规范文件的形式, 对全公司使用 C#进行的编程过程, 进行有效的规范管理, 使得最终的软件产品具有良好的风格和统一的结构, 且使代码可读性强、易维护。
本规范预期读者是全公司所有参与编程的软件开发人员以及其他相关人员。
本标准适用于 Visual C# ,其余语言作参考。
1.2 背景
公司在上一个项目中由于代码编写风格不统一, 可读性较差、较难维护, 使得工作效率有所降低。
1.3 定义
无
1.4 参考资料
Pascal Standards FAQ (E) JavaDoc （E）
Doc-O-matic Document (E) Artemis Alliance Delphi Coding Standards (E) 《C#基本书写规范》 《C#编码规范纲要》
2 2 基本要求
2.1 程序结构要求
程序结构清晰, 简单易懂, 单个函数的程序行数一般不得超过 100 行,个别特殊函数除外。
代码中打算干什么, 要简单, 直接了当, 代码精简, 避免垃圾程序。
应尽量使用.NET库函数和公共函数(无特殊情况不要使用外部方法调用windows的核心动态链接库)。
一般情况下, 不得使用全局变量, 尽量使用局部变量。
2.2 可读性要求
可读性第一, 效率第二。（这仅对代码本身而言）。
保持注释与代码完全一致。
每个源程序文件, 都必须有文件头说明, 说明规格见“源程序文档注释规范”一节。
每个函数, 都必须有函数头说明, 说明规格见“源程序文档注释规范”一节。
主要变量（结构、联合、类或对象）定义或引用时, 注释必须能反映其物理含义。
处理过程的每个阶段都必须有相关注释说明。
在典型算法前都必须有注释, 同时算法在满足要求的情况下应尽可能简单。
利用缩进来显示程序的逻辑结构, 缩进量一致以 Tab 键为单位, 定义 Tab 为 4 个 字节。
循环、分支层次不要超过五层。
注释可以与语句在同一行, 也可以在上行。
空行和空白字符也是一种特殊注释。
一目了然的语句不加注释。
注释的作用范围可以为：定义、引用、条件分支以及一段代码。
注释行数（不包括文件头和函数头说明部份）应占总行数的 1/5 到 1/3。
常量定义（const）有相应说明。
2.3 结构化要求
禁止出现两条等价的支路。
禁止 GOTO 语句。
用 IF 语句来强调只执行两组语句中的一组。禁止 ELSE GOTO 和 ELSE RETURN。
用 CASE 实现多路分支。
避免从循环引出多个出口。
函数只有一个出口。
不使用复杂的条件赋值语句。
避免不必要的分支。
不要轻易用条件分支去替换逻辑表达式。
2.4 正确性与容错性要求
程序首先是正确, 其次是优美。
无法证明你的程序没有错误, 因此在编写完一段程序后, 应先回头检查。
改一个错误时可能产生新的错误, 因此在修改前首先考虑对其它程序的影响。
所有变量在调用前必须被初始化。
对所有的用户输入, 必须进行合法性检查。
不要比较浮点数的相等, 如：
10.0 * 0.1 == 1.0 ,
不可靠。
程序与环境或状态发生关系时, 必须主动去处理发生的意外事件, 如文件能否逻辑锁定、打印机是否联机等,对于明确的错误,要有明确的容错代码提示用户。
单元测试也是编程的一部份, 提交联调测试的程序必须通过单元测试。
尽量使用规范的容错语句。
例如: try { } catch
{ } finally { }
2.5 可重用性要求
重复使用的完成相对独立功能的算法或代码应抽象为服务或类。
服务或类应考虑面向对象(OO)思想, 减少外界联系, 考虑独立性或封装性。
3 3 用户界面设计原则
除标题部分外, 所有显示给用户的字体（如BUTTON和LABEL等）使用标准字体：宋 体、九号、黑色；标题部分可用醒目的字体, 如：宋体、小二号、红色。
采用Windows缺省的风格。
窗体尽量从已有的父窗体继承。
方便用户对信息的输入、修改和阅读。
验证用户输入的有效性和合理性。
具有清晰明确的用户提示信息。
使用Tab键在输入项之间移动输入焦点（可选）。
标准按钮大小必须相同, 使用的图像和标题必须与《界面风格规范》一致, 如果出现该规范中没有的地方, 须与项目负责人和美工协商。
4 4 源程序书写规范
4.1 通用源代码格式规则
4.1.1 缩进 缩进就是每级间有一个 Tab 单位。不要在源代码中放置制表符。这是因为, 制表符的宽度随着不同的设置和代码管理实用程序(打印、文档及版本控制等)而不同。
沿逻辑结构行缩进代码。没有缩进, 代码将变得难以理解, 如：
if(expression )
{
//
//此处填写你的代码块；
//
}
if(expression )
{
//
//此处填写你的代码块；
//
}
else
{
//
//此处填写你的代码块；
// }
缩进代码会产生出更容易阅读的代码, 如：
if(expression )
{ if(expression )
{
//
//此处填写你的代码块；
//
}
else
{
//
//此处填写你的代码块；
//
}
}
4.1.2 边距
边距设置为 80 个字符。源代码一般不会因写一个单词而超过边距, 但本规则比较灵活。只要可能, 长度超过一行的语句应当用分行符换行。换行后, 应缩进两个字符。
4.1.3 “{} ”的使用 “{”或“}”必须单独占一行。例如:
错误形式：
for（i:=0；i<10；i++）{ // 错, “{” 与 f o r 在同一行
}
正确形式：
for（i:=0；i<10；i++）
// 对, “{”在另外一行中 { }
4.1.4 注释 通常使用“/*...*/”类型的块注释和“//”类型的行注释。
4.2 语句格式与语句书写规范
4.2.1 括号
在左括号与下一字符之间没有空格。同样, 右括号与前一字符也没有空格。下面的例子演示了正确与不正确的空格。
CallProc( aParameter )； // 错!
CallProc(aParameter)； // 正确!
4.2.2 保留字和关键字 在用户的各种命名中不能单独使用保留字或关键字来进行命名。
4.2.3 函数 4.2.3.1 格式
函数名要能体现出该函数要实现的功能, 应当以大写字母开始, 且大小写交错以增加可读性(每个单词的首字母大写)。下面是一个不正确的写法：
pubilc void thisisapoorlyformattedroutinename() 下面是正确的写法：
pubilc void ThisIsMuchMoreReadableRoutineName()
4.2.3.2 形参
1 1 ）
参数顺序
形参的顺序主要要考虑寄存器调用规则。最常用的参数应当作为第一个参数, 按使用频率依次从左到右排。输入参数位于输出参数之前。范围大的参数应当放在范围小的参数之前。例如：
SomeProc(aPlanet, aContinent, aCountry, aState, aCity).
有些则例外。例如, 在事件处理过程中, Object 类型的 Sender 参数往往是第一个要传递的参数。
2 2 ）
常量参数
任何值类型参数, 只要不加REF标志, 都是常量参数； 任何引用类型参数, 都不是常量参数, 不管加不加标志。
4.2.4 变量 4.2.4.1 局部变量
局部变量用于过程内部, 如果需要的话, 应当在过程的入口处立即初始化变量。
4.2.4.2 全局变量
一般不鼓励使用全局变量。不过, 有时候需要用到。即使如此, 也应当把全局变量限制在需要的环境中。例如, 一个全局变量可能只在单元的实现部分是全局的。
全局数据如果将由许多单元使用, 就应移动到一个公用单元里被所有对象使用。全局数据可在声明时直接初始化为一个值。
4.2.5 语句 4.2.5.1 If 语句
在 if/else 语句中,
if 子句的条件应该直接且易于理解。为了避免出现许多 if 语句, 可以使用 switch 语句代替。如果多于 5 级, 不要使用 if 语句。请改用更清楚的方法。
如果在 if 语句中有多个条件要测试, 应按照计算的复杂程度从右向左排。这样, 可以使代码充分利用编译器的短路估算逻辑。例如, 如果 Condition1 比 Condition2 快, Condition2 比 Condition3 快, 则 if 语句一般应这样构造：
if （Condition1 && Condition2 && Condition3）
如果 Condition3 为 False 的机会很大, 利用短路估算逻辑, 我们也可以将Condition3 放在最前面：
if （Condition3 && Condition1 && Condition2）
有 if 出现,就必须有对应的 else 出现。if 语句的三种形式: 1) 形式一(不需要 else)
if (Condition) {
Process； } //else //{ //
No Else Needed //} 2) 形式二(需要 else,但是 else 里面不需要处理)
if (Condition) {
Process； } else { //No Need Process } 3) 形式三(if 里面不需要处理)
if (Condition) { // No Need Process } else { Process； }
4.2.5.2 switch
语句
1 1 ）概述
switch 语句中每种情况的常量应当按数字或字母的顺序排列。每种情况的动作语句应当简短且通常不超过 4 - 5 行代码。如果动作太复杂, 应将代码单独放在一个函数中。switch 语句的 else 子句只用于默认情况或错误检测。
2 2 ）格式
switch 语句遵循一般的缩进和命名规则。
4.2.5.3 while 语句
所有对 while 循环进行初始化的代码应当位于 while 入口前, 且不要被无关的语句隔开。任何业务的辅助工作都应在循环后立即进行。
4.2.5.4 for 语句
如果循环次数是确定的, 应当用 for 语句代替 while 语句。
5 5 命名规范
5.1 函数命名
函数名应当有意义。进行一个动作的函数最好在名称前加上表示动作的动词为前缀。例如：
public void FormatHardDrive()
设置输入参数值的函数名应当以 Set 为其前缀, 例如：
public void SetUserName()
获取数值的函数名应当以 Get 为其前缀, 例如：
public string GetUserName() 函数名称第一个字母必须使用大写字母,要求用大小写字母组合规范函数命名,必要时可用下划线间隔,示例如下：
public void PrintTrackData() public void ShowChar(int aIndex, char aszMyChar)
5.2 形参
所有形参的名称都应当表达出它的用途。如果合适的话, 形参的名称最好以字母 a 为前缀, 例如：
public void SomeProc(string aUserName, integer aUserAge) 当参数名与类的特性或字段同名时, 前缀 a 就有必要了。
5.3 常量和变量
5.3.1 常量和宏定义
常量和宏定义必须具有一定的实际意义；常量和宏定义必须全部以大写字母,中间可根据意义的连续性用下划线连接,每一条定义的右侧必须有一简单的注释,说明其作用。
资源名字定义格式: 菜单:IDM_XX 或者 CM_XX 位图:IDB_XX 对话框:IDD_XX 字符串:IDS_XX DLGINIT:DIALOG_XX ICON:IDR_XX
5.3.2 变量
变量命名必须具有一定的实际意义,形式为 xAbcFgh,x 由变量类型确定,Abc、Fgh 表示连续意义字符串,如果连续意义字符串仅两个,可都大写, 如 OK 。
常用的变量举例如下:
以下面字母或符号作为前缀, 分别具有如下意义：
x,y
坐标 att
表属性 c
类对象 cMain（对象实例）
m_
类成员变量 m_nVal, m_bFlag s_
类静态成员变量 s_nVal,s_bFlag
5.3.2.1 局部变量
局部变量遵循其他变量的命名规则。通常以“n”作为前缀。
局部变量中可采用如下几个通用变量：nTemp, nResult, I, J（一般用于循环变量）。
5.3.2.2 全局变量
全局变量一般以字母“g”打头, 并遵循其他变量的命名规则。
5.4 函数使用说明、接口命名、e NameSpace 命名
函数使用说明包括外来函数及内部函数的使用说明, 外部引用函数必须在右侧注明函数来源：
模块名及文件名, 如是内部函数, 只要注释“local module”即可。例如：
strName=GetUserName(strUserId)；// local module strName= GetUserName(strUserId)；// Module Name:UserManage
// File Name: fm UserManage
事件函数的使用说明:
public void EventHandler(object sd,Event e)
//Event 表示事件响应的函数。
接口命名：
缩写 类型 举例 dt DateTime dtText sz char szText sb sbyte sbText bt byte btText n int nText ui uint uiText l long lText ul ulong ulText f float fText d double dText b bool bText de decimal deText str string strText
接口的命名一般都以“I”作为首字母,为了和类区分,例如:
interface IComnunication
命名空间：
命名空间命名规则从原则上和函数命名相同。通常格式如下：
NameSpace 命名：N + 部署位置 + 项目名称
+ namespace 名称
其他：
Application 命名
P + 部署位置 + 项目名称
5.5 控件的命名
C#控件规则为了和.net 类库统一,分 WindowsForm 程序和 Web 程序。下面就这两部分分别描述。
1 1 ）m WindowsForm 程序
（用小写前缀表示类别）
fm 窗口 cmd 按钮 cob combo, 下拉式列表框 txt 文本输入框 lab labal, 标签 img image, 图象 pic picture grd Grid, 网格 scr 滚动条 lst 列表框 frm fram 2 2 ）b Web 程序
（用大写前缀表示类别）
Fm 窗口 Cmd 按钮 Cob combo, 下拉式列表框 Txt 文本输入框 Lab labal, 标签 Img image, 图象 Pic picture Grd Grid, 网格 Scr 滚动条 Lst 列表框 Frm fram
5.6 类型
5.6.1 一般类型 5.6.1.1 枚举型
枚举类型名必须代表枚举的用途。枚举类型的标识符列表的前缀应包含 2 - 3 个小写字符, 来彼此关联。例如：
enum SongType={stRock, stClassical, stCountry, stAlternative, stHeavyMetal, stRB}；
5.6.2 构造类型 5.6.2.1 数组类型
数组类型名应表达出该数组的用途。例如：
string[] weekDays = new string[7]； 字符串型数组 weekDays 包括 7 个元素。
5.6.2.2 结构体类型
结构体类型命名必须全部用大写字母,原则上前面以下划线开始；结构体变量命名必须用大小写字母组合, 第一个字母必须使用大写字母,必要时可用下划线间隔。对于私有数据区, 必须注明其所属的进程。全局数据定义只需注意其用途。
示例如下：
public struct DBS_DATABASE { char szProductName[20]；
char szAuthor[20]；
char szReleaseDate[16]；
char szVersion[10]；
unsigned long MaxTables；
unsigned long UsedTables；
}
DBS_DATABASE GdataBase；
5.6.3 类类型
5.6.3.1 类命名与格式
类的名称应当表达出类的用途。一般的类名前要加字母“C”, 如果是接口类那么类名前要加“I”, 错误异常类的类名前要加“E”, 而类引用类型（Class-reference type）则要在类名后加“Class”, 抽象类一般是在类名前还要加“Abstract”。
5.6.3.2 属性命名规则
属性的命名遵循与变量相同的规则, 只不过要加前缀“f”, 表示这是属性。
5.6.3.3 方法命名规则
方法的命名遵循与过程和函数相同的规则。
5.7 文件和文件夹
5.7.1 文件夹的命名规则
根据系统设计所规定的结构, 建立相应的文件夹, 根据需要建立子文件夹； 文件夹的名称应尽量能够表达其意义, 尽量使用英文命名；
文件夹名称遵循本文命名规范。
5.7.2 文件命名 文件的名称应尽量能够表达其意义, 尽量英文命名, 不能使用汉字。文件名称遵循本文命名规范。对于各种类型的文件主要分以下三大类来描述其命名规则：
1）窗体文件
frm+表示窗体意义的词语或其缩写 2）一般类文件
cls+表示类意义的词语或其缩写 3）控件文件 cn+表示控件意义的词语或其缩写
6 6 源程序文档注释规范
书写注释的目的主要有二：
一是为自己以后阅读源程序提供方便； 二是为建立规范的程序文档手册, 提供接口说明。
6.1 注释文档的一般规范
原则上注释要求使用中文； 文件开始注释内容包括:公司名称、版权、作者名称、时间、模块用途、背景介绍等,复杂的算法需要加上流程说明； 函数注释包括:输入、输出、函数描述、流程处理、全局变量、调用样例等,复杂的函数需要加上变量用途说明； 程序中注释包括:修改时间和作者、方便理解的注释等；
例一: 文件开头的注释模板 /************************************************************** ** 文件名: ** Copyright (c) 1998-1999 *********公司技术开发部 ** 创建人: ** 日 期: ** 修改人: ** 日 期: ** 描 述: ** ** 版 本: **------------------------------------------------------------------------ *************************************************************/
例二: 函数开头的注释模板 复杂的函数应采用如下的模板：
/************************************************************* ** 函数名: ** 输 入: a,b,c ** a--- ** b--- ** c--- ** 输 出: x--- ** x 为 1, 表示... ** x 为 0, 表示... ** 功能描述: ** 全局变量: ** 调用模块: ** 作 者: ** 日 期: ** 修 改: ** 日 期: ** 版本: *************************************************************/ 简单的函数可以采用 C#的标准注释方法, 如：
/// <summary> /// 清理所有正在使用的资源。
/// </summary>
例三: 程序中的注释模板 程序中的多行注释应采用如下注释：
/*----------------------------------------------------------*/ /* 注释内容 */ /*----------------------------------------------------------*/
以下内容为：
制定规范的目的和意义
(一) 标准化为科学管理奠定了基础。所谓科学管理, 就是依据生产技术的发展规律和客观经济规律对企业进行管理, 而各种科学管理制度的形式, 都以标准化为基础。
(二) 促进经济全面发展, 提高经济效益。标准化应用于科学研究, 可以避免在研究上的重复劳动;应用于产品设计, 可以缩短设计周期;应用于生产, 可使生产在科学的和有秩序的基础上进行;应用于管理, 可促进统一、协调、高效率等。
(三)标准化是科研、生产、使用三者之间的桥梁。一项科研成果, 一旦纳入相应标准, 就能迅速得到推广和应用。因此, 标准化可使新技术和新科研成果得到推广应用, 从而促进技术进步;
(四)标准化为组织现代化生产创造了前提条件。
随着科学技 术的发展, 生产的社会化程度越来越高, 生产规模越来越大, 技术要求越来越复杂, 分工越来越细, 生产协作越来越广泛, 这就必须通过制定和使用标准, 来保证各生产部门的活动, 在技术上保持高度的统一和协调, 以使生产正常进行;所以, 我们说标准化为组织现代化生产创造了前提条件。
(五)促进对自然资源的合理利用, 保持生态平衡, 维护人类社会当前和长远的利益。标准化是经过多次实践后得出的最为有效的形式, 对于资源的利用率也是比较高的, 所以标准化在资源的合理化利用方面是有着积极意义的。
(六)合理发展产品品种, 提高企业应变能力, 以更好的满足社会需求。标准化是对当前产品的精炼, 是针对市场需求的的细分, 把最适合的保留下来, 这样将更好的满足社会的需求。
(七)保证产品质量, 维护消费者利益。标准化的规定的程序进行, 将人为因素对产品质量的影响降到最低, 确保了产品质量。
(八) 在社会生产组成部分之间进行协调, 确立共同遵循的准则, 建立稳定的秩序。
标准化的采用, 提高了企业产品之间的兼容性, 减少了由于企业产品之间标准不一致, 带来的巨大社会浪费。另外, 企业通过标准化可以避免对某一个供货商的依赖, 因为其他供货商依据公开的标准可以补充市场, 于是企业的供货渠道不断增加。供应商数量的增加, 加大了供货商之间的竞争, 从而促使产品质量不断提高, 价格也会不断降低, 建维护了市场稳定的秩序
(九)在消除贸易障碍, 促进国际技术交流和贸易发展, 提高产品在国际市场上的竞争能力方面具有重大作用。加入 WTO 以来, 面对技术壁垒, 我国在大力提高产品质量的同时, 必须依靠标准化工作提高技术水平, 提升保障产品质量, 才能在国际贸易方面有一定的话语权, 稳定促进国际贸易发展。
(十) 保障身体健康和生命安全, 大量的环保标准、卫生标准和安全标准制定发布后, 用法律形式强制执行, 对保障人民的身体健康和生命财产安全具有重大作用。
(十一)标准化标志着一个行业新的标准的产生。标准化是产品质量和技术发展一定水平才能实现的, 标准化实现将进一步促使生产技术的提高, 进行形成更高水平的标准。
总之, 标准及标准化所具有的引导性、前瞻性、公平性、强制性和惩戒性, 决定了标准化在市场经济中的作用是多层次的、全方位的, 进而也决定了
它是建立和完善市场经济体制不可缺少的重要元素。应用标准化的目的就是为了能有效解决市场经济发展中的质
量问题、效率问题、秩序问题、可持续发展问题等。因此, 我们必须从战略的高度重视标准化工作。只有我们不断地去提升标准化水平, 才能有效提升产品质量, 增强产品的市场竞争力, 进一步扩大出口贸易, 从而有效推进经济社会又好又快向前发展。
