StyleCop——默认的规则

使用StyleCop进行代码审查

工欲善其事，必先利其器，上篇简单介绍了怎样使用Astyle进行代码格式化，使编写的代码具有一致的风格。今天简单介绍下怎样使用StyleCop对原代码进行审查，看编写的代码是否遵循设计规范、.Net约定和一些贯用法等。保证代码的一致性，可读性等等。

 

在此之前，先简单介绍下FxCop（起初只是微软内部使用的工具）,一个分析托管程序集，检测代码的总体正确性的工具，告诉用户哪些地方不符合设计规范。他使用的评估规则已经发展了多年，凝聚了顶尖.Net框架开发人员的知识和技术。但是FxCop是基于托管代码分析的，即编译后的程序集。今天我们介绍的StyleCop同样是用来检查代码是否符合设计规范的，它是基于原代码验证的，仅支持C#语言，就是在开发期间进行代码验证的工具，相信在日常开发中，会帮助到大家，在使用工具的同时，逐渐改善和提高大家的编码规范和意识，另外，相关内容推荐大家读下《.Net设计规范-.Net约定、贯用法与模式》这本书。好了，入题：

 

首先，还是先下载最新版的StyleCop.

下载地址：http://stylecop.codeplex.com/

当前最新版本是StyleCop-4.7.37.0.msi，版本4.7，下载完成后，开始安装，安装过程非常简单，这里就不上图了。安装完成后，好像没什么反应，在开始菜单也不会出现相关菜单。没关系，现在打开Visual Studio，我以Visual Studio2010为例，见下图：

 

在项目菜单上会出现StyleCop相关菜单。

点击“Run StyleCop”，呵，警告一大堆，见下图：

StyleCop已经把不符合规范的相关警告全部列出，并且已经定位到行和列，双击任一条项目即可定位到问题点。

 

也可以基于单个文件进行检查，只要在当前代码页右键点击“Run StyleCop”即可，见下图：

 

其中检验的规则可在项目名称的右键菜单“StyleCop Settings”中设定，见下图，使用中发现对中文支持的不是很好。其中一些不适用的校验规则可以不勾选即可。

 

下面主要对一些常见的警告简单说明：

 

SA1633 : CSharp.Documentation : The file has no header, the header Xml is invalid, or the header is not located at the top of the file.

代码不包含文件头说明，格式如下。

//-----------------------------------------------------------------------

// <copyright file="Widget.cs" company="Sprocket Enterprises">

//     Copyright (c) Sprocket Enterprises. All rights reserved.

// </copyright>

// <author>John Doe</author>

//-----------------------------------------------------------------------

 

SA1507 : CSharp.Layout : The code must not contain multiple blank lines in a row.

代码部分存在多个空格

 

SA1600 : CSharp.Documentation : The method must have a documentation header.

方法必须要头部说明，只要在方法前键入3个斜杠，IDE自动会根据该方法生成相关头文档说明。

 

SA1400 : CSharp.Maintainability : The class must have an access modifier.

类必须要有一个访问修饰符，如：public、private等。

 

SA1513 : CSharp.Layout : Statements or elements wrapped in curly brackets must be followed by a blank line.

语句之间要有空行。

 

SA1202 : CSharp.Ordering : All private methods must be placed after all public methods.

私有方法要放在公有方法子后。

 

SA1650 : CSharp.Documentation : The documentation text within the summary tag contains incorrectly spelled words: 异常测试

这个是对中文支持的不够好。拼写检查识别不到。

其他还有常见的变量首字母小，常量首字母大写，等等常规检查，其它规则请参见StyleCop使用说明。

 

附录：

在StyleCop中有一些官方自己写好的检测规则下面就是英文的解释
文档规则
1、SA1600：ElementsMustBeDocumented元素必须添加注释

2、SA1601: PartialElementsMustBeDocumented Partial修饰的成员必须添加注释

3、SA1602：EnumerationItemsMustBeDocumented 枚举必须添加注释

4、SA1603: DocumentationMustContainValidXml 注释必须合法(注释中的关键字不能有错误)

5、SA1604: ElementDocumentationMustHaveSummary 元素注释必须包含Summary关键字

6、SA1605:PartialElementDocumentationMustHaveSummary Partial修饰的成员注释必须包含Summary关键字

7、SA1606:ElementDocumentationMustHaveSummaryText Summary节点内部必须添加文本

8、SA1607:PartialElementDocumentationMustHaveSummaryText Partial修饰的成员注释Summary节点内部必须添加文本

9、SA1608:ElementDocumentationMustNotHaveDefaultSummary Summary注释不能使用编译器自带的注释文本

10、SA1609:PropertyDocumentationMustHaveValue 属性的注释中必须包含<Value>节点

11、SA1610:PropertyDocumentationMustHaveValueText 属性的注释<Value>节点必须包含文本值

12、SA1611:ElementParametersMustBeDocumented 参数必须注释

13、SA1612:ElementParameterDocumentationMustMatchElementParameters 参数的个数必须与注释里的个数一致

14、SA1613:ElementParameterDocumentationMustDeclareParameterName 参数的注释里必须有参数的名称

15、SA1614:ElementParameterDocumentationMustHaveText 参数注释节点里不能空着

16、SA1615:ElementReturnValueMustBeDocumented 返回值必须添加注释

17、SA1616:ElementReturnValueDocumentationMustHaveText 返回值注释的节点内必须有文本值

18、SA1617:VoidReturnValueMustNotBeDocumented 空返回值一定不能有返回值注释

19、SA1618:GenericTypeParametersMustBeDocumented 生成的类型(泛型)参数必须有注释

20、SA1619:GenericTypeParametersMustBeDocumentedPartialClass SA1618情况如果有Partial类存在都要有注释

21、SA1620:GenericTypeParameterDocumentationMustMatchTypeParameters 注释与泛型必须能匹配上

22、SA1621:GenericTypeParameterDocumentationMustDeclareParameterName 泛型的注释必须包含泛型定义是的关键字(如’T’)

23、SA1622:GenericTypeParameterDocumentationMustHaveText 泛型的注释节点中必须包含文本值

24、SA1623:PropertySummaryDocumentationMustMatchAccessors 属性的注释必须与属性的读写权限匹配，private类型的属性不能出现在注释里

25、SA1624:PropertySummaryDocumentationMustOmitSetAccessorWithRestrictedAccess 属性的注释里必须忽略protected关键字，当成public类型当注释

26、SA1625:ElementDocumentationMustNotBeCopiedAndPasted 各个参数的注解不能完全相同(避免copy、post行为)

27、SA1626:SingleLineCommentsMustNotUseDocumentationStyleSlashes 单行注释不能采取三个斜线的注释方式，斜线的个数必须是二的倍数

28、SA1627:DocumentationTextMustNotBeEmpty 注释节点内部不能为空(必须有文本值)

29、SA1628:DocumentationTextMustBeginWithACapitalLetter 注释节点内部的文本必须以大写字母开头

30、SA1629:DocumentationTextMustEndWithAPeriod 注释节点内部的文本必须英文的句号结束

31、SA1630:DocumentationTextMustContainWhitespace 注释节点内部的文本必须包含空格

32、SA1631:DocumentationMustMeetCharacterPercentage 注释节点内部的文本中不能包含过多的字符(举例:包含’---------------------------------------’是不允许的)

33、SA1632:DocumentationTextMustMeetMinimumCharacterLength 已经作废的规则，不允许有太短的字符串(如’A name’ 中的A字母)

34、SA1633:FileMustHaveHeader 代码文件头部必须有说明，一般放置版权信息

35、SA1634:FileHeaderMustShowCopyright 代码文件头部注解中必须包含版权关键字

36、SA1635:FileHeaderMustHaveCopyrightText代码文件头部注解中必须包含版权信息内同

37、SA1636:FileHeaderCopyrightTextMustMatch 代码文件头部注解中版权信息必须与设置画面设置的内容相匹配，在”style seting”画面的” Company Information tab”进行设置

38、SA1637:FileHeaderMustContainFileName 代码文件头部注解中必须包含文件名称

39、SA1638:FileHeaderFileNameDocumentationMustMatchFileName 代码文件头部注解中必须包含文件名称必须与实际的名称匹配

40、SA1639:FileHeaderMustHaveSummary 代码文件头部注解中必须包含Summary节点

41、SA1640:FileHeaderMustHaveValidCompanyText 代码文件头部注解中版权信息必须含有合理的公司名字

42、SA1641:FileHeaderCompanyNameTextMustMatch 代码文件头部注解中的公司名字必须与设置画面设置的内容相匹配，在”style seting”画面的” Company Information tab”进行设置

43、SA1642:ConstructorSummaryDocumentationMustBeginWithStandardText 构造函数注释标准：“Initializes a new instance of the <see cref="Customer{T}"/> class.”

44、SA1643:DestructorSummaryDocumentationMustBeginWithStandardText 析构函数注释标准：“Finalizes an instance of the <see cref="Customer"/> class.”

45、SA1644:DocumentationHeadersMustNotContainBlankLines 注释中不能出现空白行

46、SA1645:IncludedDocumentationFileDoesNotExist 如果注释中包含文件，要确定这个文件存在，举例：“ /// <include file="IncludedDocumentation.xml" path="root/EnabledMethodDocs" />” 这一项过于复杂不建议用，但是如果将来想规范化相同共性东西的注释的时候倒是可以考虑引入。

47、SA1646:IncludedDocumentationXPathDoesNotExist 如果注释中包含文件，路径不存在。

48、SA1647:IncludeNodeDoesNotContainValidFileAndPath 如果注释中包含文件 文件与路径都要合法

49、SA1648:InheritDocMustBeUsedWithInheritingClass 这项不明白是什么意思，还请知道的分享给我，谢谢。

50、SA1649:FileHeaderFileNameDocumentationMustMatchTypeName 文件头注释必须匹配类型

51、SA1650:ElementDocumentationMustBeSpelledCorrectly 注释不能有拼写错误(对中文支持不好，不建议使用该项)

布局规则

1、 SA1500:CurlyBracketsForMultiLineStatementsMustNotShareLine 花括号不能再同一行。

标准格式： public StRsvrRFun()

{

}

2、SA1501:StatementMustNotBeOnASingleLine 语句不能共享一行

3、SA1502:ElementMustNotBeOnASingleLine 语句不能共享一行

4、SA1503:CurlyBracketsMustNotBeOmitted 花括弧即使在单行代码的情况下也不能省略。

5、SA1504:AllAccessorsMustBeSingleLineOrMultiLine 读写属性，要么在同一行业要么在分多行写，不可规则不统一(个人建议分多行写)。

6、SA1505:OpeningCurlyBracketsMustNotBeFollowedByBlankLine 开始的花括弧后面不能有空白行

7、SA1506:ElementDocumentationHeadersMustNotBeFollowedByBlankLine 元素头部注释跟元素之间不能有空白行

8、SA1507:CodeMustNotContainMultipleBlankLinesInARow 不允许有多行空白行紧挨着(个人建议写一个空白行即可)

9、SA1508:ClosingCurlyBracketsMustNotBePrecededByBlankLine 结尾的花括弧不能再一个空白行之前

10、SA1509:OpeningCurlyBracketsMustNotBePrecededByBlankLine 开始的花括弧不能再一个空白行之前

11、SA1510:ChainedStatementBlocksMustNotBePrecededByBlankLine 相连的语句之间不能有空白行，如try语句与catch语句之间不能有空白行

12、SA1511:WhileDoFooterMustNotBePrecededByBlankLine 与SA1510相同，Do语句与While语句之间不能有空白行

13、SA1512:SingleLineCommentsMustNotBeFollowedByBlankLine 单行注释不能后跟空白行

14、SA1513:ClosingCurlyBracketMustBeFollowedByBlankLine 结束花括弧之后必须有一个空白行

15、SA1514:ElementDocumentationHeaderMustBePrecededByBlankLine 头部注解之前必须有一个空白行

16、SA1515:SingleLineCommentMustBePrecededByBlankLine 单行注释之前要有一个空白行，还一种方法是不加空白行而用四个斜线注释”////”,建议采取第一种方法

17、SA1516:ElementsMustBeSeparatedByBlankLine 邻近的元素之间要有一个空白行

18、SA1517:CodeMustNotContainBlankLinesAtStartOfFile 代码文件头部字符之前不能出现空白行

19、SA1518:CodeMustNotContainBlankLinesAtEndOfFile代码文件尾部字符之后不能出现空白行

可维护规则

1、 SA1119:StatementMustNotUseUnnecessaryParenthesis 语句中不可以出现多余的括弧，无意义的括弧增加了代码的可读性

2、 SA1400:AccessModifierMustBeDeclared 必须定义访问修饰符

3、 SA1401:FieldsMustBePrivate 字段必须定义为私有的

4、 SA1402:FileMayOnlyContainASingleClass 一个CS文件里只定义一个类

5、 SA1403:FileMayOnlyContainASingleNamespace 一个CS文件只包含一个命名空间

6、 SA1404:CodeAnalysisSuppressionMustHaveJustification Suppression特性(取消报告特定的静态分析工具规则冲突，允许一个代码项目上应用多个取消报告设置)必须要有合理理由

7、 SA1405:DebugAssertMustProvideMessageText 参见代码：“Debug.Assert(value != true, "The value must always be true.");”

8、 SA1406:DebugFailMustProvideMessageText 参见代码：“Debug.Fail("The code should never reach this point.");”

9、 SA1407:ArithmeticExpressionsMustDeclarePrecedence 算数表达式必须用明确的标明其优先级(此条与SA1119冲突)

10、 SA1408:ConditionalExpressionsMustDeclarePrecedence 条件表达式必须明确的标明其优先级(此条与SA1119冲突) 举例：“if (x || (y && z && a) || b)”

11、 SA1409:RemoveUnnecessaryCode 移除无用的代码

12、 SA1410:RemoveDelegateParenthesisWhenPossible 调用一个c#匿名方法不包含任何方法参数,必须要包括一个空括号(本人不建议使用匿名方法、匿名委托的语法，具体原因后续做分享)

13、 SA1411:AttributeConstructorMustNotUseUnnecessaryParenthesis 特性构造函数如果是空参的形式，不要包括那个空括号

命名规则

1、 SA1300:ElementMustBeginWithUpperCaseLetter 首字母必须大写(个人理解应该是字段以外的东西)

2、 SA1301: ElementMustBeginWithLowerCaseLetter 不会出现的情况

3、 SA1302:InterfaceNamesMustBeginWithI 接口必须以“I”字母开头

4、 SA1303:ConstFieldNamesMustBeginWithUpperCaseLetter Const常量首字母大写

5、 SA1304:NonPrivateReadonlyFieldsMustBeginWithUpperCaseLetter 非私有非制度的字段必须首字母大写

6、 SA1305:FieldNamesMustNotUseHungarianNotation 除了列表外的字符不可以出现匈牙利命名规则,在”Style Setting”里的” Hungarian”Tab里设置

7、 SA1306:FieldNamesMustBeginWithLowerCaseLetter 字段名必须首字母小写

8、 SA1307:AccessibleFieldsMustBeginWithUpperCaseLetter public或者internal字段首字母大写

9、 SA1308:VariableNamesMustNotBePrefixed 变量名不能有前缀

10、 SA1309:FieldNamesMustNotBeginWithUnderscore 字段名不能以下滑线开头

11、 SA1310:FieldNamesMustNotContainUnderscore 字段名不能包括下滑线

12、 SA1311:StaticReadonlyFieldsMustBeginWithUpperCaseLetter static与readonly字段首字母大写

排序规则

1、SA1200:UsingDirectivesMustBePlacedWithinNamespace using部分必须在Namespace内部(个人不建议用这个规则)

2、SA1201:ElementsMustAppearInTheCorrectOrder 所有的元素必须出现在正确的位置上(个人不建议使用该规则，用region把一个类文件里的元素分好组即可，字段、属性、对外公布的接口、私有方法等组)

3、SA1202:ElementsMustBeOrderedByAccess 元素的修饰符有一个固定的顺序(个人不建议使用该规则，用region把一个类文件里的元素分好组即可，字段、属性、对外公布的接口、私有方法等组)

4、SA1203:ConstantsMustAppearBeforeFields 常量字段摆放在其它字段之上

5、SA1204:StaticElementsMustAppearBeforeInstanceElements Static 元素摆放在前面

6、SA1205:PartialElementsMustDeclareAccess Partial修饰的元素必须声明读写权限

7、SA1206:DeclarationKeywordsMustFollowOrder 举例：

keywords must appear in the following order:

Access modifiers

static

All other keywords

8、SA1207:ProtectedMustComeBeforeInternal Protected在Internal之前

9、SA1208:SystemUsingDirectivesMustBePlacedBeforeOtherUsingDirectives 系统级的引用在其他引用之前(格式化代码就会自动按照这个规则编排using部分)

10、SA1209:UsingAliasDirectivesMustBePlacedAfterOtherUsingDirectives using部分起别名的在最后排布

11、SA1210:UsingDirectivesMustBeOrderedAlphabeticallyByNamespace using部分按照字母顺序编排

12、SA1211:UsingAliasDirectivesMustBeOrderedAlphabeticallyByAliasName 别名的按照别名的字母编排

13、SA1212:PropertyAccessorsMustFollowOrder 属性按照先get在set

14、SA1213:EventAccessorsMustFollowOrder 时间先remove在add

15、SA1214:StaticReadonlyElementsMustAppearBeforeStaticNonReadonlyElements StaticReadonly元素在StaticNonReadonly元素之前

16、SA1215:InstanceReadonlyElementsMustAppearBeforeInstanceNonReadonlyElements

一个readonly 实例元素要在一个非readonly 实例元素

可读性规则

1、 SA1100:DoNotPrefixCallsWithBaseUnlessLocalImplementationExists

change the ‘base.’ prefix to ‘this.’.

2、 SA1101:PrefixLocalCallsWithThis ‘this.’前缀不能省略

3、 SA1102:QueryClauseMustFollowPreviousClause linq语句要么同一行，要么关键字分布在多行，关键字对齐

4、 SA1103:QueryClausesMustBeOnSeparateLinesOrAllOnOneLine 不是很理解

5、 SA1104:QueryClauseMustBeginOnNewLineWhenPreviousClauseSpansMultipleLines不是很理解

6、 SA1105:QueryClausesSpanningMultipleLinesMustBeginOnOwnLine不是很理解

7、 SA1106:CodeMustNotContainEmptyStatements 不允许有空白的声明

8、 SA1107:CodeMustNotContainMultipleStatementsOnOneLine 同一行里不允许出现多个声明语句

9、 SA1108:BlockStatementsMustNotContainEmbeddedComments 非法用例：

if (x != y)

// Make sure x does not equal y

{

}

10、 SA1109:BlockStatementsMustNotContainEmbeddedRegions 非法用例：

if (x != y)

#region

{

}

#endregion

11、 SA1110:OpeningParenthesisMustBeOnDeclarationLine 方法开始的括弧要在声明的那一行

12、 SA1111:ClosingParenthesisMustBeOnLineOfLastParameter 方法结束括弧与最后一个参数同行

13、 SA1112:ClosingParenthesisMustBeOnLineOfOpeningParenthesis 如果是空参的情况，开始于结束括弧在同一行

14、 SA1113:CommaMustBeOnSameLineAsPreviousParameter 逗号必须与前一个参数同行

15、 SA1114:ParameterListMustFollowDeclaration

确保参数列表与开始括号同行，或者另起一行 参数整体要在同一行

16、 SA1115:ParameterMustFollowComma 参数与参数之间不能隔空白行

17、 SA1116:SplitParametersMustStartOnLineAfterDeclaration 所有参数在同一行或者如下示例：

public string JoinName(

string first,

string last)

18、SA1117:ParametersMustBeOnSameLineOrSeparateLines 同上

19、SA1118:ParameterMustNotSpanMultipleLines 实际调用是参数要在同一行

20、SA1120:CommentsMustContainText 注释必须节点内部必须有文本

22、SA1122:UseStringEmptyForEmptyStrings

示例代码：“string s = string.Empty;”不能写成” string s = ""; ”

23、SA1123:DoNotPlaceRegionsWithinElements 不使用region(个人较反对这条，个人倾向于用region规整类里的元素)

24、SA1124:DoNotUseRegions 不使用region(个人较反对这条，个人倾向于用region规整类里的元素)

25、SA1125:UseShorthandForNullableTypes 使用简写版的可空类型 如”int?”

26、SA1126:PrefixCallsCorrectly 调用类成员的时候要带上“this”前缀

拼写规则

1、 SA1000:KeywordsMustBeSpacedCorrectly 关键字不能拼写错误

2、 SA1001:CommasMustBeSpacedCorrectly 逗号前面摆放一个空格

3、 SA1002:SemicolonsMustBeSpacedCorrectly 分号前面摆放一个空格

4、 SA1003:SymbolsMustBeSpacedCorrectly 操作符与元素之间不加空格

5、 SA1004:DocumentationLinesMustBeginWithSingleSpace “///”注释的每一行以一个空格开头

6、 SA1005:SingleLineCommentsMustBeginWithSingleSpace 单行注释以一个空格开头

7、 SA1006:PreprocessorKeywordsMustNotBePrecededBySpace 预处理关键字内部不允许出现空格 如“# if Debug”是不允许的

8、 SA1007:OperatorKeywordMustBeFollowedBySpace 操作必须要在一个空格之后

9、 SA1008:OpeningParenthesisMustBeSpacedCorrectly 开始括弧放置合理的空格

10、 SA1009:ClosingParenthesisMustBeSpacedCorrectly 结尾括弧放置合理的空格

11、 SA1010:OpeningSquareBracketsMustBeSpacedCorrectly 开始方括号放置合理的空格

12、 SA1011:ClosingSquareBracketsMustBeSpacedCorrectly 结束方括号放置合理的空格

13、 SA1012:OpeningCurlyBracketsMustBeSpacedCorrectly 开始花括号放置合理的空格

14、 SA1013:ClosingCurlyBracketsMustBeSpacedCorrectly 结束花括号放置合理的空格

15、 SA1014:OpeningGenericBracketsMustBeSpacedCorrectly 同上

16、 SA1015:ClosingGenericBracketsMustBeSpacedCorrectly 同上

17、 SA1016:OpeningAttributeBracketsMustBeSpacedCorrectly 特性开始括号同上

18、 SA1017:ClosingAttributeBracketsMustBeSpacedCorrectly 特性结尾括号同上

19、 SA1018:NullableTypeSymbolsMustNotBePrecededBySpace 空类型前不放置空格

20、 SA1019:MemberAccessSymbolsMustBeSpacedCorrectly 成员访问关键字前后有空格

21、 SA1020:IncrementDecrementSymbolsMustBeSpacedCorrectly 自增、自减关键字要有空格

22、 SA1021:NegativeSignsMustBeSpacedCorrectly 负号要有空格

23、 SA1022:PositiveSignsMustBeSpacedCorrectly 正号要有空格

24、 SA1023:DereferenceAndAccessOfMustBeSpacedCorrectly

25、 SA1024:ColonsMustBeSpacedCorrectly 冒号运算符要有空格

26、 SA1025:CodeMustNotContainMultipleWhitespaceInARow 同一行不允许出现多个空格

27、 SA1026:CodeMustNotContainSpaceAfterNewKeywordInImplicitlyTypedArrayAllocation new关键字之后不允许出现空格

28、 SA1027:TabsMustNotBeUsed 不用tab字符(个人不建议采用这条)