Version 2.0 目录
第一章 概述.... 2
规范制定原则... 2
术语定义... 2
Pascal 大小写... 2
Camel 大小写... 2
文件命名组织... 2
1.3.1文件命名... 2
1.3.2文件注释... 2
第二章 代码外观.... 2
2.1 列宽... 2
2.2 换行... 2
2.3 缩进... 2
2.4 空行... 2
2.5 空格... 2
2.6 括号 - () 2
2.7 花括号 - {}. 2
第三章 程序注释.... 2
3.4 注释概述... 2
3.2 文档型注释... 2
3.3 类c注释... 2
3.4 单行注释... 2
3.5 注释标签... 2
第四章 申明.... 2
4.1 每行声明数... 2
4.2 初始化... 2
4.3 位置... 2
4.4 类和接口的声明... 2
4.5 字段的声明... 2
第五章 命名规范.... 2
5.1 命名概述... 2
5.2 大小写规则... 2
5.3 缩写... 2
5.4 命名空间... 2
5.5 类... 2
5.6 接口... 2
5.7 属性 (Attribute). 2
5.8 枚举 (Enum). 2
5.9 参数... 2
5.10 方法... 2
5.11 属性 (property). 2
5.12 事件... 2
5.13 常量 (const). 2
5.14 字段... 2
5.15 静态字段... 2
5.16 集合... 2
5.17 措词... 2
第六章 语句.... 2
6.1 每行一个语句... 2
6.2 复合语句... 2
6.3 return 语句... 2
6.4 if、 if-else、if else-if 语句... 2
6.4 for、foreach 语句... 2
6.5 while 语句... 2
6.7. do - while 语句... 2
6.8. switch - case 语句... 2
6.9. try - catch 语句... 2
6.10. using 块语句... 2
6.11. goto 语句... 2
第七章 控件命名规则.... 2
7.1 命名方法... 2
7.2 主要控件名简写对照表... 2
第八章 其他.... 2
8.1 表达式... 2
8.2 类型转换... 2
附录一: 匈牙利命名法.... 2
1 方便代码的交流和维护。
2 不影响编码的效率,不与大众习惯冲突。
3 使代码更美观、阅读更方便。
4 使代码的逻辑更清晰、更易于理解。
将标识符的首字母和后面连接的每个单词的首字母都大写。可以对三字符或更多字符的标识符使用Pascal 大小写。例如:
BackColor
标识符的首字母小写,而每个后面连接的单词的首字母都大写。例如:
backColor
1.3.1文件命名
1 文件名遵从Pascal命名法,无特殊情况,扩展名小写。
2 使用统一而又通用的文件扩展名: C# 类 .cs
1.3.2文件注释
1 在每个文件头必须包含以下注释说明
/*----------------------------------------------------------------
// Copyright (C) 2004 XXXX有限公司
// 版权所有。
//
// 文件名:
// 文件功能描述:
//
//
// 创建标识:
//
// 修改标识:
// 修改描述:
//
// 修改标识:
// 修改描述:
//----------------------------------------------------------------*/
文件功能描述只需简述,具体详情在类的注释中描述。
创建标识和修改标识由创建或修改人员的拼音或英文名加日期组成。如:
李轶20040408
一天内有多个修改的只需做一个在注释说明中做一个修改标识就够了。
在所有的代码修改处加上修改标识的注释。
代码列宽控制在110字符左右。
当表达式超出或即将超出规定的列宽,遵循以下规则进行换行
1、在逗号后换行。
2、 在操作符前换行。
3、规则1优先于规则2。
当以上规则会导致代码混乱的时候自己采取更灵活的换行规则。
缩进应该是每行一个Tab(4个空格),不要在代码中使用Tab字符。
Visual Studio.Net设置:工具->选项->文本编辑器->C#->制表符->插入空格
空行是为了将逻辑上相关联的代码分块,以便提高代码的可阅读性。
在以下情况下使用两个空行
1、接口和类的定义之间。
2、枚举和类的定义之间。
3、类与类的定义之间。
在以下情况下使用一个空行
1、方法与方法、属性与属性之间。
2、方法中变量声明与语句之间。
3、方法与方法之间。
4、方法中不同的逻辑块之间。
5、方法中的返回语句与其他的语句之间。
6、属性与方法、属性与字段、方法与字段之间。
7、注释与它注释的语句间不空行,但与其他的语句间空一行。
在以下情况中要使用到空格
1、 关键字和左括符 “(” 应该用空格隔开。如
while (true)
注意在方法名和左括符 “(” 之间不要使用空格,这样有助于辨认代码中的方法调用与关键字。
2、 多个参数用逗号隔开,每个逗号后都应加一个空格。
3、 除了 . 之外,所有的二元操作符都应用空格与它们的操作数隔开。一元操作符、++及--与操作 数间不需要空格。如
a += c + d;
a = (a + b) / (c * d);
while (d++ = s++)
{
n++;
}
PrintSize(“size is “ + size + “\n”);
4、语句中的表达式之间用空格隔开。如
for (expr1; expr2; expr3)
2.6 括号 - ()
1、 左括号“(” 不要紧靠关键字,中间用一个空格隔开。
2、 左括号“(” 与方法名之间不要添加任何空格。
3、 没有必要的话不要在返回语句中使用()。如
if (condition)
Array.Remove(1)
return 1
2.7 花括号 - {}
1、 左花括号 “{” 放于关键字或方法名的下一行并与之对齐。如
if (condition)
{
}
public int Add(int x, int y)
{
}
2、 左花括号 “{” 要与相应的右花括号 “}”对齐。
3、 通常情况下左花括号 “{”单独成行,不与任何语句并列一行。
4、 if、while、do语句后一定要使用{},即使{}号中为空或只有一条语句。如
if (somevalue == 1)
{
somevalue = 2;
}
5、 右花括号 “}” 后建议加一个注释以便于方便的找到与之相应的 {。如
while (1)
{
if (valid)
{
} // if valid
else
{
} // not valid
} // end forever
1、修改代码时,总是使代码周围的注释保持最新。
2、在每个例程的开始,提供标准的注释样本以指示例程的用途、假设和限制很有帮助。注释样本应该是解释它为什么存在和可以做什么的简短介绍.
3、避免在代码行的末尾添加注释;行尾注释使代码更难阅读。不过在批注变量声明时,行尾注释是合适的;在这种情况下,将所有行尾注释在公共制表位处对齐。
4 、避免杂乱的注释,如一整行星号。而是应该使用空白将注释同代码分开。
5 、避免在块注释的周围加上印刷框。这样看起来可能很漂亮,但是难于维护。
6 、在部署发布之前,移除所有临时或无关的注释,以避免在日后的维护工作中产生混乱。
7 、如果需要用注释来解释复杂的代码节,请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码,而应该重写它。尽管一般不应该为了使代码更简单以便于人们使用而牺牲性能,但必须保持性能和可维护性之间的平衡。
8 、在编写注释时使用完整的句子。注释应该阐明代码,而不应该增加多义性。
9 、在编写代码时就注释,因为以后很可能没有时间这样做。另外,如果有机会复查已编写的代码,在今天看来很明显的东西六周以后或许就不明显了。
10 、避免多余的或不适当的注释,如幽默的不主要的备注。
11、 使用注释来解释代码的意图。它们不应作为代码的联机翻译。
12、 注释代码中不十分明显的任何内容。
13 、为了防止问题反复出现,对错误修复和解决方法代码总是使用注释,尤其是在团队环境中。
14 、对由循环和逻辑分支组成的代码使用注释。这些是帮助源代码读者的主要方面。
15 、在整个应用程序中,使用具有一致的标点和结构的统一样式来构造注释。
16 、用空白将注释同注释分隔符分开。在没有颜色提示的情况下查看注释时,这样做会使注释很明显且容易被找到。
17 、在所有的代码修改处加上修改标识的注释。
18 、为了是层次清晰,在闭合的右花括号后注释该闭合所对应的起点。
namespace Langchao.Procument.Web
{
} // namespace Langchao.Procument.Web
该类注释采用.Net已定义好的Xml标签来标记,在声明接口、类、方法、属性、字段都应该使用该类注释,以便代码完成后直接生成代码文档,让别人更好的了解代码的实现和接口。如
///<summary>MyMethod is a method in the MyClass class.
///<para>Here's how you could make a second paragraph in a description.
///<see cref="System.Console.WriteLine"/>
///for information about output statements.
///</para>
///<seealso cref="MyClass.Main"/>
///</summary>
public static void MyMethod(int Int1)
{
}
该类注释用于
1 不再使用的代码。
2 临时测试屏蔽某些代码。
用法
/*
[修改标识]
[修改原因]
. . . (the source code )
*/
该类注释用于
1 方法内的代码注释。如变量的声明、代码或代码段的解释。注释示例:
//
// 注释语句
//
private int number;
或
// 注释语句
private int number;
2 方法内变量的声明或花括号后的注释, 注释示例:
if ( 1 == 1) // always true
{
statement;
} // always true
标签
|
用法
|
作用
|
<c>
|
c>text</c>
text 希望将其指示为代码的文本。
|
为您提供了一种将说明中的文本标记为代码的方法。使用 <code> 将多行指示为代码
|
<para>
|
<para>content</para>
content段落文本。
|
用于诸如 <remarks> 或 <returns> 等标记内,使您得以将结构添加到文本中。
|
<param>
|
<param name='name'>description</param>
name 为方法参数名。将此名称用单引号括起来 (' ')。
|
应当用于方法声明的注释中,以描述方法的一个参数。
|
<paramref>
|
<paramref name="name"/>
name
要引用的参数名。将此名称用双引号括起来 (" ")。
|
<paramref> 标记为您提供了一种指示词为参数的方法。可以处理 XML 文件,从而用某种独特的方法格式化该参数。
|
<see>
|
<see cref="member"/>
cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后,将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ") 中。
|
使您得以从文本内指定链接。使用 <seealso> 指示希望在“请参阅”一节中出现的文本。
|
<seealso>
|
<seealso cref="member"/>
cref = "member" 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查到给定代码元素存在后,将 member 传递给输出 XML 中的元素名。必须将 member 括在双引号 (" ") 中
|
使您得以指定希望在“请参阅”一节中出现的文本。使用 <see> 从文本
|
<example>
|
<example>description</example>
description
代码示例的说明。
|
使用 <example> 标记可以指定使用方法或其他库成员的示例。一般情况下,这将涉及到 <code> 标记的使用。
|
<code>
|
<code>content</code>
content 为希望将其标记为代码的文本。
|
记为您提供了一种将多行指示为代码的方法。使用 <c> 指示应将说明中的文本标记为代码
|
<summary>
|
<summary>description</summary>
此处description 为对象的摘要。
|
应当用于描述类型成员。使用 <remarks> 以提供有关类型本身的信息。
|
<exception>
|
<exception cref="member">description</exception>
cref = "member" 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后,将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。
description 说明。
|
<exception> 标记使您可以指定类能够引发的异常。
|
<include>
|
<include file='filename' path='tagpath[@name="id"]' />
filename 包含文档的文件名。该文件名可用路径加以限定。将 filename 括在单引号中 (' ')。
Tagpath:filename 中指向标记名的标记路径。将此路径括在单引号中 (' ')。
name 注释前边的标记中的名称说明符;名称具有一个 id。
id
位于注释之前的标记的 id。将此 id 括在双引号中 (" ")。
|
<include> 标记使您得以引用描述源代码中类型和成员的另一文件中的注释。这是除了将文档注释直接置于源代码文件中之外的另一种可选方法。
<include> 标记使用 XML XPath 语法。有关自定义 <include> 使用的方法,请参阅 XPath 文档。
|
<list>
|
<list type="bullet" | "number" | "table">
<listheader>
<term>term</term>
<description>description</description& |
|
请发表评论