不说废话,大牛初始亦菜鸟,成功之路贵执行,马上行动!如果想获得更优质的显示效果,请在Chrome、Firefox等现代浏览器浏览本站。

团队项目开发”编码规范”之八:代码格式检查

:: 挨踢业界 EricHu 850℃ 0评论

团队项目开发”编码规范”之八:

代码格式检查

 

发布日期:2011318星期三作者:EricHu

 

                                                                                                                      勤能补拙、笨鸟先飞。

  

代码格式检查使用微软内部代码检查工具 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

元素必须被注释

     ///

    /// Joins a first name and a last name together into a single string.

    ///

    /// The first name to join.

    /// The last name to join.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

        return firstName + ” ” + lastName;

}

SA1601: PartialElementsMustBeDocumented

部分元素必须被注释

///

    /// Documentation for the first part of Class1.

    ///

    public partial class Class1

    {

    }

 

    ///

    /// Documentation for the second part of Class1.

    ///

    public partial class Class1

    {

}

SA1602: EnumerationItemsMustBeDocumented

枚举项必须被注释

///

    /// Types of animals.

    ///

    public enum Animals

    {

        ///

        /// Represents a dog.

        ///

        Dog,

 

        ///

        /// Represents a cat.

        ///

        Cat,

 

        ///

        /// Represents a horse.

        ///

        Horse

    }

SA1603: DocumentationMustContainValidXml

文档必须包含有效的XML注释

    ///

    /// An example of badly formed Xml.

    ///

    public class Example

    {

    }

SA1604: ElementDocumentationMustHaveSummary

文档注释必须包含Summary

    ///

    /// Represents a customer in the database.

    ///

    public class Customer

    {

    }

SA1605: PartialElementDocumentationMustHaveSummary

部分文档注释必须包含Summary

///

    /// Documentation for the first part of Class1.

    ///

    public partial class Class1

    {

    }

 

    ///

    /// Documentation for the second part of Class1.

    ///

    public partial class Class1

    {

    }

SA1606: ElementDocumentationMustHaveSummaryText

文档注释Summary必须有内容

///

 

/// The ID of the customer to find.

/// The customer, or null if the customer could not be

/// found.

public Customer FindCustomer(int customerId)

{

    // … finds the customer …

}

SA1607: PartialElementDocumentationMustHaveSummaryText

部分文档注释Summary必须有内容

///

 

/// The ID of the customer to find.

/// The customer, or null if the customer could not be found.

public Customer FindCustomer(int customerId)

{

    // … finds the customer …

}

 

修复代码

///

Attempts to locate a record for the customer with the given ID.

/// The ID of the customer to find.

/// The customer, or null if the customer could not be found.

public Customer FindCustomer(int customerId)

{

    // … finds the customer …

}

SA1608: ElementDocumentationMustNotHaveDefaultSummary

文档注释不能有默认的Summary

    ///

    /// Summary description for the Example class.

    ///

    public class Example

    {

    }

SA1609: PropertyDocumentationMustHaveValue

属性注释必须有值

  ///

    /// Gets the name of the customer.

    ///

    /// The name of the customer.

    public bool Name

    {

        get { return this.name; }

    }

SA1610: PropertyDocumentationMustHaveValueText

属性注释必须有值内容

  ///

    /// Gets the name of the customer.

    ///

    /// The name of the customer.

    public bool Name

    {

        get { return this.name; }

    }

SA1611: ElementParametersMustBeDocumented

元素的参数必须注释

///

    /// Joins a first name and a last name together into a single string.

    ///

    /// The first name to join.

    /// The last name to join.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

        return firstName + ” ” + lastName;

    }

SA1612: ElementParameterDocumentationMustMatchElementParameters

元素的参数注释必须与元素参数成对

   ///

    /// Joins a first name and a last name together into a single string.

    ///

    /// The first name to join.

    /// The last name to join.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

        return firstName + ” ” + lastName;

    }

SA1613: ElementParameterDocumentationMustDeclareParameterName

元素的参数注释必须定义参数名

    ///

    /// Joins a first name and a last name together into a single string.

    ///

    /// The first name to join.

    /// The last name to join.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

        return firstName + ” ” + lastName;

    }

SA1614: ElementParameterDocumentationMustHaveText

元素的参数注释必须有值

    ///

    /// Joins a first name and a last name together into a single string.

    ///

    /// The first name to join.

    /// The last name to join.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

        return firstName + ” ” + lastName;

    }

SA1615: ElementReturnValueMustBeDocumented

元素的返回值必须被注释

    ///

    /// Joins a first name and a last name together into a single string.

    ///

    /// The first name to join.

    /// The last name to join.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

        return firstName + ” ” + lastName;

    }

SA1616: ElementReturnValueDocumentationMustHaveValue

元素的返回值注释必须有值

    ///

    /// Joins a first name and a last name together into a single string.

    ///

    /// The first name to join.

    /// The last name to join.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

        return firstName + ” ” + lastName;

    }

SA1617: VoidReturnValueMustNotBeDocumented

元素空返回值不能注释

   ///

    /// Prints the given name.

    ///

    /// The first name.

    /// The last name.

    public void PrintNames(string firstName, string lastName)

    {

        Console.WriteLine(firstName + ” ” + lastName);

    }

SA1618: GenericTypeParametersMustBeDocumented

泛型参数必须被注释

   ///

    /// A sample generic class.

    ///

    /// The first generic type parameter.

    /// The second generic type parameter.

    public class Class1

    {

    }

SA1619: GenericTypeParametersMustBeDocumentedPartialClass

泛型参数在部分类中必须被注释

   ///

    /// A sample generic class.

    ///

    /// The first generic type parameter.

    /// The second generic type parameter.

    public class Class1

    {

    }

SA1620: GenericTypeParameterDocumentationMustMatchTypeParameters

泛型参数注释必须与参数类型对应

    ///

    /// A sample generic class.

    ///

    /// The first generic type parameter.

    /// The second generic type parameter.

    public class Class1

    {

    }

SA1621: GenericTypeParameterDocumentationMustDeclareParameterName

泛型参数注释必须定义参数名

    ///

    /// A sample generic class.

    ///

    /// The first generic type parameter.

    /// The second generic type parameter.

    public class Class1

    {

    }

SA1622: GenericTypeParameterDocumentationMustHaveText

泛型参数注释必须有内容

    ///

    /// A sample generic class.

    ///

    /// The first generic type parameter.

    /// The second generic type parameter.

    public class Class1

    {

    }

SA1623: PropertySummaryDocumentationMustMatchAccessors

属性摘要文档必须和访问者对应

(参考帮助文档)

SA1624: PropertySummaryDocumentationMustOmitSetAccessorWithRestricedAccess

属性摘要文档必须必须省略设置访问器约束访问

(参考帮助文档)

SA1625: ElementDocumentationMustNotBeCopiedAndPasted

元素注释不能被拷贝和粘贴

    ///

    /// Joins a first name and a last name together into a single string.

    ///

    /// The first name to join.

    /// The last name to join.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

        return firstName + ” ” + lastName;

    }

SA1626: SingleLineCommentsMustNotUseDocumentationStyleSlashes

单行注释不能使用斜线样式

    ///

    /// Joins a first name and a last name together into a single string.

    ///

    /// Part of the name.

    /// Part of the name.

    /// The joined names.

    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

注释内容不能为空

    ///

    /// Joins a first name and a last name together into a single string.

    ///

    ///

    /// Part of the name.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

       

    }

SA1628: DocumentationTextMustBeginWithACapitalLetter

注释内容首字母必须大写

    ///

    /// joins a first name and a last name together into a single string.

    ///

    /// The first name.

    /// The last name.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

       

    }

SA1629: DocumentationTextMustEndWithAPeriod

注释内容必须用句号结尾

    ///

    /// Joins a first name and a last name together into a single string

    ///

    /// The first name.

    /// The last name.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

       

    }

SA1630: DocumentationTextMustContainWhitespace

注释内容单词之间必须包含空白符

    ///

    /// Joinsnames

    ///

    /// First

    /// Last

    /// Name

    public string JoinNames(string firstName, string lastName)

    {

       

    }

 

SA1631: DocumentationTextMustMeetCharacterPercentage

注释内容必须满足字符比例特殊字符不能过多

    ///

    /// @)$(*A name——–

    ///

    public class Name   

    {

       

    }

 

SA1632: DocumentationTextMustMeetMinimumCharacterLength

注释内容必须满足小写字符长度

    ///

    /// A name

    ///

    public class Name   

    {

       

    }

SA1633: FileMustHaveHeader

文件必须有文件头部注释

//———————————————————————–

//

//     Company copyright tag.

//

//———————————————————————–

 

For example, a file called Widget.cs from a fictional company called Sprocket Enterprises should contain a file header similar to the following:

//———————————————————————–

//

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

//

//———————————————————————–

 

The dashed lines at the top and bottom of the header are not strictly necessary, so the header could be written as:

//

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

//

 

It is possible to add additional tags, although they will not be checked or enforced by StyleCop:

//———————————————————————–

//

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

//

// John Doe

//———————————————————————–

SA1634: FileHeaderMustShowCopyright

文件头部注释必须显示版权信息标识

//———————————————————————–

// A file header which does not contain a copyright tag

//———————————————————————–

 

A file header should include a copyright tag, as follows:

//———————————————————————–

//

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

//

//———————————————————————–

SA1635: FileHeaderMustHaveCopyrightText

文件头部注释必须有版权信息表示内容

//———————————————————————–

//

//

//———————————————————————–

 

A file header should include copyright text, as follows:

//———————————————————————–

//

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

//

//———————————————————————–

SA1636: FileHeaderMustContainFileName

文件头部注释必须包含文件名

//———————————————————————–

//

//     Custom company copyright tag.

//

//———————————————————————–

SA1637: FileHeaderMustContainFileName

文件头部注释必须包含文件名

//———————————————————————–

//

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

//

//———————————————————————–

 

//———————————————————————–

//

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

//

//———————————————————————–

SA1638: FileHeaderFileNameDocumentationMustMatchFileName

文件头部注释文件名注释必须与文件名对应

//———————————————————————–

//

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

//

//———————————————————————–

 

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 (c) Sprocket Enterprises. All rights reserved.

//

//———————————————————————–

SA1639: FileHeaderMustHaveSummary

文件头部注释不许有摘要

//———————————————————————–

//

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

//

//———————————————————————–

 

If this rule is enabled, the file header should contain a summary tag. For example:

//———————————————————————–

//

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

//

//

Defines the Widget class.

//———————————————————————–

SA1640: FileHeaderMustHaveValidCompanyText

文件头部注释必须有正确的公司信息

//———————————————————————–

//

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

//

//———————————————————————–

SA1641: FileHeaderCompanyNameTextMustMatch

文件头部注释公司内容必须对应

//———————————————————————–

//

//     Custom company copyright tag.

//

//———————————————————————–

SA1642: ConstructorSummaryDocumentationMustBeginWithStandardText

构造器的Summary注释必须由标准内容开始

(参考帮助文档)

SA1643: DestructorSummaryDocumentationMustBeginWithStandardText

析构器的Summary注释必须由标准内容开始

    ///

    /// Initializes a new instance of the class.

    ///

    public Customer()

    {

    }

 

    ///

    /// Initializes a new instance of the class.

    ///

    public Customer()

    {

    }

SA1644: DocumentationHeadersMustNotContainBlankLines

注释头部不能包含空白行

    ///

    ///

    /// Joins a first name and a last name together into a single string.

    ///

    /// Uses a simple form of string concatenation.

    ///

    ///

    /// The first name to join.

    /// The last name to join.

    /// The joined names.

    public string JoinNames(string firstName, string lastName)

    {

        return firstName + ” ” + lastName;

    }

SA1645: IncludedDocumentationFileDoesNotExist

导入的文档注释文件不存在

    ///

    public bool Enabled(bool true)

    {

    }

 

SA1646: IncludedDocumentationXPathDoesNotExist

导入的文档注释的XPath不存在

    ///

    public bool Enabled(bool true)

    {

    }

SA1647: IncludeNodeDoesNotContainValidFileAndPath

导入的结点不存在正确的文件和路径

    ///

    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

字段名不能包含“_”

 

转载请注明:RDIFramework.NET » 团队项目开发”编码规范”之八:代码格式检查

喜欢 (0)or分享 (0)
发表我的评论
取消评论

表情

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址