开发总结
代码格式检查使用微软内部代码检查工具 StyleCop 版本 4.3.2 .1 ，它会根据预定义的 C# 代码格式的最佳实践，对源代码进行检查，并给出不符合编码风格的错误提示（版本语言英文）。
8.1 检查分类
检查规则分为 7 个部分，分别是
“文档规则 (Documentation Rules) ”
“ 布局规则 (LayoutRules)”
“可维护性规则 (Maintanability Rules) ”
“ 命名规则 (Naming Rules)”
“ 代码顺序规则 (Ordering Rules)”
“ 可读性规则 (Readability Rules)”
“ 间距规则 (Spacing Rules)”
8.2 安装及使用
安装：安装程序位于附件， Install 文件夹中。该软件属于 Visual Studio 插件，安装后在工具菜单栏中。
使用：运行该功能后，可以根据“错误列表”中的警告信息的信息 Id ，从帮助文件（位于附件， Document 文件夹中，文件名 StyleCop.chm ）找到相应编码格式，进行修复。
开发文档：位于附件， Document 文件夹中，文件名 StyleCopSDK.chm ）
对于以下情况 “是否检查”一项中为“ √ ”的内容不能违反。
8.3 文档规则 (Documentation Rules)
标识及提示
中文及示例
是否检查
SA1600: ElementsMustBeDocumented
元素必须被注释
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}
√
SA1601: PartialElementsMustBeDocumented
部分元素必须被注释
/// <summary>
/// Documentation for the first part of Class1.
/// </summary>
public partial class Class1
{
}
/// <summary>
/// Documentation for the second part of Class1.
/// </summary>
public partial class Class1
{
}
√
SA1602: EnumerationItemsMustBeDocumented
枚举项必须被注释
/// <summary>
/// Types of animals.
/// </summary>
public enum Animals
{
/// <summary>
/// Represents a dog.
/// </summary>
Dog,
/// <summary>
/// Represents a cat.
/// </summary>
Cat,
/// <summary>
/// Represents a horse.
/// </summary>
Horse
}
√
SA1603: DocumentationMustContainValidXml
文档必须包含有效的 XML 注释
/// <summary>
/// An example of badly formed Xml.
/// </summa3ry>
public class Example
{
}
√
SA1604: ElementDocumentationMustHaveSummary
文档注释必须包含 Summary
/// <summary>
/// Represents a customer in the database.
/// </summary>
public class Customer
{
}
√
SA1605: PartialElementDocumentationMustHaveSummary
部分文档注释必须包含 Summary
/// <summary>
/// Documentation for the first part of Class1.
/// </summary>
public partial class Class1
{
}
/// <summary>
/// Documentation for the second part of Class1.
/// </summary>
public partial class Class1
{
}
√
SA1606: ElementDocumentationMustHaveSummaryText
文档注释 Summary 必须有内容
/// <summary> </summary>
/// <param name="customerId">The ID of the customer to find.</param>
/// <returns>The customer, or null if the customer could not be
/// found.</returns>
public Customer FindCustomer(int customerId)
{
// ... finds the customer ...
}
√
SA1607: PartialElementDocumentationMustHaveSummaryText
部分文档注释 Summary 必须有内容
/// <summary> </summary>
/// <param name="customerId">The ID of the customer to find.</param>
/// <returns>The customer, or null if the customer could not be found.</returns>
public Customer FindCustomer(int customerId)
{
// ... finds the customer ...
}
修复代码
/// <summary>Attempts to locate a record for the customer with the given ID.</summary>
/// <param name="customerId">The ID of the customer to find.</param>
/// <returns>The customer, or null if the customer could not be found.</returns>
public Customer FindCustomer(int customerId)
{
// ... finds the customer ...
}
√
SA1608: ElementDocumentationMustNotHaveDefaultSummary
文档注释不能有默认的 Summary
/// <summary>
/// Summary description for the Example class.
/// </summary>
public class Example
{
}
√
SA1609: PropertyDocumentationMustHaveValue
属性注释必须有值
/// <summary>
/// Gets the name of the customer.
/// </summary>
/// <value>The name of the customer.</value>
public bool Name
{
get { return this.name; }
}
√
SA1610: PropertyDocumentationMustHaveValueText
属性注释必须有值内容
/// <summary>
/// Gets the name of the customer.
/// </summary>
/// <value>The name of the customer.</value>
public bool Name
{
get { return this.name; }
}
√
SA1611: ElementParametersMustBeDocumented
元素的参数必须注释
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}
√
SA1612: ElementParameterDocumentationMustMatchElementParameters
元素的参数注释必须与元素参数成对
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}
√
SA1613: ElementParameterDocumentationMustDeclareParameterName
元素的参数注释必须定义参数名
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}
√
SA1614: ElementParameterDocumentationMustHaveText
元素的参数注释必须有值
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}
√
SA1615: ElementReturnValueMustBeDocumented
元素的返回值必须被注释
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}
√
SA1616: ElementReturnValueDocumentationMustHaveValue
元素的返回值注释必须有值
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}
√
SA1617: VoidReturnValueMustNotBeDocumented
元素空返回值不能注释
/// <summary>
/// Prints the given name.
/// </summary>
/// <param name="firstName">The first name.</param>
/// <param name="lastName">The last name.</param>
public void PrintNames(string firstName, string lastName)
{
Console.WriteLine(firstName + " " + lastName);
}
√
SA1618: GenericTypeParametersMustBeDocumented
泛型参数必须被注释
/// <summary>
/// A sample generic class.
/// </summary>
/// <typeparam name="S">The first generic type parameter.</typeparam>
/// <typeparam name="T">The second generic type parameter.</typeparam>
public class Class1<S, T>
{
}
√
SA1619: GenericTypeParametersMustBeDocumentedPartialClass
泛型参数在部分类中必须被注释
/// <summary>
/// A sample generic class.
/// </summary>
/// <typeparam name="S">The first generic type parameter.</typeparam>
/// <typeparam name="T">The second generic type parameter.</typeparam>
public class Class1<S, T>
{
}
√
SA1620: GenericTypeParameterDocumentationMustMatchTypeParameters
泛型参数注释必须与参数类型对应
/// <summary>
/// A sample generic class.
/// </summary>
/// <typeparam name="S">The first generic type parameter.</typeparam>
/// <typeparam name="T">The second generic type parameter.</typeparam>
public class Class1<S, T>
{
}
√
SA1621: GenericTypeParameterDocumentationMustDeclareParameterName
泛型参数注释必须定义参数名
/// <summary>
/// A sample generic class.
/// </summary>
/// <typeparam name="S">The first generic type parameter.</typeparam>
/// <typeparam name="T">The second generic type parameter.</typeparam>
public class Class1<S, T>
{
}
√
SA1622: GenericTypeParameterDocumentationMustHaveText
泛型参数注释必须有内容
/// <summary>
/// A sample generic class.
/// </summary>
/// <typeparam name="S">The first generic type parameter.</typeparam>
/// <typeparam name="T">The second generic type parameter.</typeparam>
public class Class1<S, T>
{
}
√
SA1623: PropertySummaryDocumentationMustMatchAccessors
属性摘要文档必须和访问者对应
( 参考帮助文档 )
√
SA1624: PropertySummaryDocumentationMustOmitSetAccessorWithRestricedAccess
属性摘要文档必须必须省略设置访问器约束访问
( 参考帮助文档 )
√
SA1625: ElementDocumentationMustNotBeCopiedAndPasted
元素注释不能被拷贝和粘贴
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}
√
SA1626: SingleLineCommentsMustNotUseDocumentationStyleSlashes
单行注释不能使用斜线样式
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">Part of the name.</param>
/// <param name="lastName">Part of the name.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
A legal comment beginning with two slashes:
// Join the names together.
string fullName = firstName + " " + lastName;
An illegal comment beginning with three slashes:
/// Trim the name.
fullName = fullName.Trim();
A line of commented-out code beginning with four slashes:
////fullName = asfd;
return fullName;
}
√
SA1627: DocumentationTextMustNotBeEmpty
注释内容不能为空
/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName"> </param>
/// <param name="lastName">Part of the name.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
...
}
√
SA1628: DocumentationTextMustBeginWithACapitalLetter
注释内容首字母必须大写
/// <summary>
/// joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name.</param>
/// <param name="lastName">The last name.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
...
}
√
SA1629: DocumentationTextMustEndWithAPeriod
注释内容必须用句号结尾
/// <summary>
/// Joins a first name and a last name together into a single string
/// </summary>
/// <param name="firstName">The first name.</param>
/// <param name="lastName">The last name.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
...
}
√
SA1630: DocumentationTextMustContainWhitespace
注释内容单词之间必须包含空白符
/// <summary>
/// Joinsnames
/// </summary>
/// <param name="firstName">First</param>
/// <param name="lastName">Last</param>
/// <returns>Name</returns>
public string JoinNames(string firstName, string lastName)
{
...
}
SA1631: DocumentationTextMustMeetCharacterPercentage
注释内容必须满足字符比例特殊字符不能过多
/// <summary>
/// @)$(*A name--------
/// </summary>
public class Name
{
...
}
SA1632: DocumentationTextMustMeetMinimumCharacterLength
注释内容必须满足小写字符长度
/// <summary>
/// A name
/// </summary>
public class Name
{
...
}
√
SA1633: FileMustHaveHeader
文件必须有文件头部注释
//-----------------------------------------------------------------------
// <copyright file="NameOfFile.cs" company="CompanyName">
// Company copyright tag.
// </copyright>
//-----------------------------------------------------------------------
For example, a file called Widget.cs from a fictional company called Sprocket Enterprises should contain a file header similar to the following:
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
The dashed lines at the top and bottom of the header are not strictly necessary, so the header could be written as:
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
It is possible to add additional tags, although they will not be checked or enforced by StyleCop:
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
// <author>John Doe</author>
//-----------------------------------------------------------------------
√
SA1634: FileHeaderMustShowCopyright
文件头部注释必须显示版权信息标识
//-----------------------------------------------------------------------
// <Tag>A file header which does not contain a copyright tag</Tag>
//-----------------------------------------------------------------------
A file header should include a copyright tag, as follows:
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
√
SA1635: FileHeaderMustHaveCopyrightText
文件头部注释必须有版权信息表示内容
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// </copyright>
//-----------------------------------------------------------------------
A file header should include copyright text, as follows:
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
√
SA1636: FileHeaderMustContainFileName
文件头部注释必须包含文件名
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="My Company">
// Custom company copyright tag.
// </copyright>
//-----------------------------------------------------------------------
√
SA1637: FileHeaderMustContainFileName
文件头部注释必须包含文件名
//-----------------------------------------------------------------------
// <copyright company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
√
SA1638: FileHeaderFileNameDocumentationMustMatchFileName
文件头部注释文件名注释必须与文件名对应
//-----------------------------------------------------------------------
// <copyright file="File2.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
A violation of this rule would occur, since the file tag does not contain the name of the file. The header should be written as:
//-----------------------------------------------------------------------
// <copyright file="File1.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
√
SA1639: FileHeaderMustHaveSummary
文件头部注释不许有摘要
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
If this rule is enabled, the file header should contain a summary tag. For example:
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
// <summary>Defines the Widget class.</summary>
//-----------------------------------------------------------------------
√
SA1640: FileHeaderMustHaveValidCompanyText
文件头部注释必须有正确的公司信息
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="Sprocket Enterprises">
// Copyright (c) Sprocket Enterprises. All rights reserved.
// </copyright>
//-----------------------------------------------------------------------
√
SA1641: FileHeaderCompanyNameTextMustMatch
文件头部注释公司内容必须对应
//-----------------------------------------------------------------------
// <copyright file="Widget.cs" company="My Company">
// Custom company copyright tag.
// </copyright>
//-----------------------------------------------------------------------
√
SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText
构造器的 Summary 注释必须由标准内容开始
( 参考帮助文档 )
√
SA1643: DestructorSummaryDocumentationMustBeginWithStandardText
析构器的 Summary 注释必须由标准内容开始
/// <summary>
/// Initializes a new instance of the <see cref="Customer`1"/> class.
/// </summary>
public Customer()
{
}
/// <summary>
/// Initializes a new instance of the <see cref="Customer{T}"/> class.
/// </summary>
public Customer()
{
}
√
SA1644: DocumentationHeadersMustNotContainBlankLines
注释头部不能包含空白行
/// <summary>
/// <para>
/// Joins a first name and a last name together into a single string.
/// </para><para>
/// Uses a simple form of string concatenation.
/// </para>
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
return firstName + " " + lastName;
}
√
SA1645: IncludedDocumentationFileDoesNotExist
导入的文档注释文件不存在
///<include file="IncludedDocumentation.xml" path="root/EnabledMethodDocs" />
public bool Enabled(bool true)
{
}
√
SA1646: IncludedDocumentationXPathDoesNotExist
导入的文档注释的 XPath 不存在
///<include file="IncludedDocumentation.xml" path="root/EnabledMethodDocs" />
public bool Enabled(bool true)
{
}
√
SA1647: IncludeNodeDoesNotContainValidFileAndPath
导入的结点不存在正确的文件和路径
///<include file="IncludedDocumentation.xml" path="root/EnabledMethodDocs" />
public bool Enabled(bool true)
{
}
√
8.4 布局规则 (LayoutRules)
标识及提示
中文及示例
是否检查
SA1500: CurlyBracketsForMultiLineStatementsMustNotShareLine
当多行代码使用 {} 时 "{" 与 "}" 必须单独占一行
√
SA1501: StatementMustNotBeOnSingleLine
{} 不能与代码写在同一行
√
SA1502: ElementMustNotBeOnSingleLine
元素定义不能在同一行
√
SA1503: CurlyBracketsMustNotBeOmitted
{} 符号不能被省略
√
SA1504: AllAccessorMustBeMultiLineOrSingleLine
所有的访问器代码，必须是多行或一行 ( 不能 Get 多行， Set 单行 )
√
SA1505: OpeningCurlyBracketsMustNotBeFollowedByBlankLine
{ 符号下面不能跟空行
√
SA1506: ElementDocumentationHeadersMustNotBeFollowedByBlankLine
元素注释头部不能跟空行
√
SA1507: CodeMustNotContainMultipleBlankLinesInARow
代码不能包含连续的多个空行
√
SA1508: ClosingCurlyBracketsMustNotBePrecededByBlankLine
} 符号上方不能有空行
√
SA1509: OpeningCurlyBracketsMustNotBePrecedededByBlankLine
{ 符号与代码之间不能有空行
√
SA1510: ChainedStatementBlocksMustNotBePrecededByBlankLine
使用 {} 符号并且连接的代码之间不能有空行
√
SA1511: WhileDoFooterMustNotBePrecededByBlankLine
Do While 代码之间不能有空行
√
SA1512: SingleLineCommentsMustNotBeFollowedByBlankLine
单行注释与代码之间不能有空行
√
SA1513: ClosingCurlyBracketMustBeFollowedByBlankLine
} 符号后面必须有空行
√
SA1514: ElementDocumentationHeaderMustBePrecededByBlankLine
元素注释头部必须加空行
√
SA1515: SingleLineCommentMustBePrecededByBlankLine
单行注释前面必须加空行
√
SA1516: ElementsMustBeSeparatedByBlankLine
元素必须用空行分隔
√
8.5 可维护性规则(Maintanability Rules)”
标识及提示
中文及示例
是否检查
SA1300: ElementMustBeginWithUpperCaseLetter
元素必须首字母大写
√
SA1301: ElementMustBeginWithLowerCaseLetter
元素必须首字母小写
√
SA1302: InterfaceNamesMustBeginWithI
命名接口必须以 I 开头
√
SA1303: ConstFieldNamesMustBeginWithUpperCaseLetter
常量字段命名必须首字母大写
√
SA1304: NonPrivateReadonlyFieldsMustBeginWithUpperCaseLetter
非私有只读字段必须首字母大写
√
SA1305: FieldNamesMustNotUseHungarianNotation
字段名不能使用匈牙利命名法
√
SA1306: FieldNamesMustBeginWithLowerCaseLetter
字段名必须首字母小写
√
SA1307: AccessibleFieldsMustBeginWithUpperCaseLetter
可访问字段必须首字母大写
√
SA1308: VariableNamesMustNotBePrefixed
变量名不能加前缀
√
SA1309: FieldNamesMustNotBeginWithUnderscore
字段名不能以 "_" 开头
√
SA1310: FieldNamesMustNotContainUnderscore
字段名不能包含 "_"
作者： Leo_wl
出处： http://HdhCmsTestcnblogs测试数据/Leo_wl/
本文版权归作者和博客园共有，欢迎转载，但未经作者同意必须保留此段声明，且在文章页面明显位置给出原文连接，否则保留追究法律责任的权利。
版权信息