[StyleCop] SA1625: ElementDocumentationMustNotBeCopiedAndPasted來源 URL： http://www.stylecop.com/docs/SA1625.html |
今天寫完某個 COM Port 的 Function之後，跑了一下StyleCop 出現了SA1625的問題。
其實我的問題就跟 SA1625 範例講的一樣，poorly written
就跟範例的一樣 firstName跟 lastName 的 寫的內容是一樣的
/// <param name="firstName">Part of the name.</param>
/// <param name="lastName">Part of the name.</param>
改一下就行了
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
TypeName
|
ElementDocumentationMustNotBeCopiedAndPasted
|
CheckId
|
SA1625
|
Category
|
Documentation Rules
|
Cause
The Xml documentation for a C# element contains two or more identical entries, indicating that the documentation has been copied and pasted. This can sometimes indicate invalid or poorly written documentation.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs when an element contains two or more identical documentation texts. For example:
/// <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)
{
return firstName + " " + lastName;
}
In some cases, a method may contain one or more parameters which are not used within the body of the method. In this case, the documentation for the parameter can be set to "The parameter is not used." StyleCop will allow multiple parameters to contain identical documentation as long as the documentation string is "The parameter is not used."
How to Fix Violations
To fix a violation of this rule, edit the documentation for the element and ensure that each of the individual documentation texts are unique. For example:
/// <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;
}
How to Suppress Violations
[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1625:ElementDocumentationMustNotBeCopiedAndPasted", Justification = "Reviewed.")]
[StyleCop] SA1005來源 URL： file:///D:/Evernote/SA1005/SA1005.rtf |
Cause
A single-line comment within a C# code file does not begin with a single space.
Rule Description
A violation of this rule occurs when a single-line comment does not begin with a single space. For example:
private void Method1()
{
//A single-line comment.
// A single-line comment.
}
The comments should begin with a single space after the leading forward slashes:
private void Method1()
{
// A single-line comment.
// A single-line comment.
}
An exception to this rule occurs when the comment is being used to comment out a line of code. In this case, the space can be omitted if the comment begins with four forward slashes to indicate out-commented code. For example:
private void Method1()
{
////int x = 2;
////return x;
}
How to Fix Violations
To fix a violation of this rule, ensure that the comment begins with a single space. If the comment is being used to comment out a line of code, ensure that the comment begins with four forward slashes, in which case the leading space can be omitted.
[StyleCop] SA1101來源 URL： file:///D:/Evernote/SA1101/SA1101.rtf |
Cause
A call to an instance member of the local class or a base class is not prefixed with 'this.', within a C# code file.
Rule Description
A violation of this rule occurs whenever the code contains a call to an instance member of the local class or a base class which is not prefixed with 'this.'. An exception to this rule occurs when there is a local override of a base class member, and the code intends to call the base class member directly, bypassing the local override. In this case the call can be prefixed with 'base.' rather than 'this.'.
By default, StyleCop disallows the use of underscores or m_ to mark local class fields, in favor of the 'this.' prefix. The advantage of using 'this.' is that it applies equally to all element types including methods, properties, etc., and not just fields, making all calls to class members instantly recognizable, regardless of which editor is being used to view the code. Another advantage is that it creates a quick, recognizable differentiation between instance members and static members, which are not be prefixed.
A final advantage of using the 'this.' prefix is that typing this. will cause Visual Studio to show the IntelliSense popup, making it quick and easy for the developer to choose the class member to call.
How to Fix Violations
To fix a violation of this rule, insert the 'this.' prefix before the call to the class member.
[StyleCop] SA1642來源 URL： file:///D:/Evernote/SA1642/SA1642.rtf |
Cause
The Xml documentation header for a C# constructor does not contain the appropriate summary text.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs when the summary tag within the documentation header for a constructor does not begin with the proper text.
The rule is intended to standardize the summary text for a constructor based on the access level of the constructor. The summary for a non-private instance constructor must begin with "Initializes a new instance of the {class name} class." For example, the following shows the constructor for the Customer class.
/// <summary>
/// Initializes a new instance of the Customer class.
/// </summary>
public Customer()
{
}
It is possible to embed other tags into the summary text. For example:
/// <summary>
/// Initializes a new instance of the <see cref="Customer"/> class.
/// </summary>
public Customer()
{
}
If the class contains generic parameters, these can be annotated within the cref link using either of the following two formats:
/// <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()
{
}
If the constructor is static, the summary text should begin with "Initializes static members of the {class name} class." For example:
/// <summary>
/// Initializes static members of the Customer class.
/// </summary>
public static Customer()
{
}
Private instance constructors must use the summary text "Prevents a default instance of the {class name} class from being created."
/// <summary>
/// Prevents a default instance of the Customer class from being created.
/// </summary>
private Customer()
{
}
How to Fix Violations
To fix a violation of this rule, edit the summary text for the constructor as described above.
[StyleCop] SA1633來源 URL： file:///D:/Evernote/SA1633/SA1633.rtf |
Cause
A C# code file is missing a standard file header.
Rule Description
A violation of this rule occurs when a C# source file is missing a file header. The file header must begin on the first line of the file, and must be formatted as a block of comments containing Xml, as follows:
//-----------------------------------------------------------------------
// <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>
//-----------------------------------------------------------------------
A file that is completely auto-generated by a tool, and which should not be checked or enforced by StyleCop, can include an "auto-generated" header rather than the standard file header. This will cause StyleCop to ignore the file. This type of header should never be placed on top of a manually written code file.
// <auto-generated />
namespace Sample.Something
{
// The contents of this file are completely auto-generated by a tool.
}
How to Fix Violations
To fix a violation of this rule, add a standard file header at the top of the file.
[StyleCop] SA1108來源 URL： file:///D:/Evernote/SA1108/SA1108.rtf |
TypeName
|
BlockStatementsMustNotContainEmbeddedComments
|
CheckId
|
SA1108
|
Category
|
Readability Rules
|
Cause
A C# statement contains a comment between the declaration of the statement and the opening curly bracket of the statement.
Rule Description
A violation of this rule occurs when the code contains a comment in between the declaration and the opening curly bracket. For example:
if (x != y)
// Make sure x does not equal y
{
}
The comment can legally be placed above the statement, or within the body of the statement:
// Make sure x does not equal y
if (x != y)
{
}
if (x != y)
{
// Make sure x does not equal y
}
If the comment is being used to comment out a line of code, begin the comment with four forward slashes rather than two:
if (x != y)
////if (x == y)
{
}
How to Fix Violations
To fix a violation of this rule, move the comment above the statement, within the body of the statement, or remove the comment.
[StyleCop] SA1116來源 URL： file:///D:/Evernote/SA1116/SA1116.rtf |
TypeName
|
SplitParametersMustStartOnLineAfterDeclaration
|
CheckId
|
SA1116
|
Category
|
Readability Rules
|
Cause
The parameters to a C# method or indexer call or declaration span across multiple lines, but the first parameter does not start on the line after the opening bracket.
Rule Description
A violation of this rule occurs when the parameters to a method or indexer span across multiple lines, but the first parameter does not start on the line after the opening bracket. For example:
public string JoinName( string first,
string last)
{
}
The parameters must begin on the line after the declaration, whenever the parameter span across multiple lines:
public string JoinName(
string first,
string last)
{
}
How to Fix Violations
To fix a violation of this rule, ensure that the first parameter starts on the line after the opening bracket, or place all parameters on the same line if the parameters are not too long.
[StyleCop] SA1200來源 URL： file:///D:/Evernote/SA1200/SA1200.rtf |
TypeName
|
UsingDirectivesMustBePlacedWithinNamespace
|
CheckId
|
SA1200
|
Category
|
Ordering Rules
|
Cause
A C# using directive is placed outside of a namespace element.
Rule Description
A violation of this rule occurs when a using directive or a using-alias directive is placed outside of a namespace element, unless the file does not contain any namespace elements.
For example, the following code would result in two violations of this rule.
using System;
using Guid = System.Guid;
namespace Microsoft.Sample
{
public class Program
{
}
}
The following code, however, would not result in any violations of this rule:
namespace Microsoft.Sample
{
using System;
using Guid = System.Guid;
public class Program
{
}
}
There are subtle differences between placing using directives within a namespace element, rather than outside of the namespace, including:
1. Placing using-alias directives within the namespace eliminates compiler confusion between conflicting types.
2. When multiple namespaces are defined within a single file, placing using directives within the namespace elements scopes references and aliases.
1. Eliminating Type Confusion
Consider the following code, which contains a using-alias directive defined outside of the namespace element. The code creates a new class called Guid, and also defines a using-alias directive to map the name Guid to the type System.Guid. Finally, the code creates an instance of the type Guid:
using Guid = System.Guid;
namespace Microsoft.Sample
{
public class Guid
{
public Guid(string s)
{
}
}
public class Program
{
public static void Main(string[] args)
{
Guid g = new Guid ("hello" );
}
}
}
This code will compile cleanly, without any compiler errors. However, it is unclear which version of the Guid type is being allocated. If the using directive is moved inside of the namespace, as shown below, a compiler error will occur:
namespace Microsoft.Sample
{
using Guid = System. Guid;
public class Guid
{
public Guid(string s)
{
}
}
public class Program
{
public static void Main(string[] args)
{
Guid g = new Guid ("hello" );
}
}
}
The code fails on the following compiler error, found on the line containing Guid g = new Guid("hello" );
CS0576: Namespace 'Microsoft.Sample' contains a definition conflicting with alias 'Guid'
The code creates an alias to the System.Guid type called Guid, and also creates its own type called Guid with a matching constructor interface. Later, the code creates an instance of the type Guid. To create this instance, the compiler must choose between the two different definitions of Guid. When the using-alias directive is placed outside of the namespace element, the compiler will choose the local definition of Guid defined within the local namespace, and completely ignore the using-alias directive defined outside of the namespace. This, unfortunately, is not obvious when reading the code.
When the using-alias directive is positioned within the namespace, however, the compiler has to choose between two different, conflicting Guid types both defined within the same namespace. Both of these types provide a matching constructor. The compiler is unable to make a decision, so it flags the compiler error.
Placing the using-alias directive outside of the namespace is a bad practice because it can lead to confusion in situations such as this, where it is not obvious which version of the type is actually being used. This can potentially lead to a bug which might be difficult to diagnose.
Placing using-alias directives within the namespace element eliminates this as a source of bugs.
2. Multiple Namespaces
Placing multiple namespace elements within a single file is generally a bad idea, but if and when this is done, it is a good idea to place all using directives within each of the namespace elements, rather than globally at the top of the file. This will scope the namespaces tightly, and will also help to avoid the kind of behavior described above.
It is important to note that when code has been written with using directives placed outside of the namespace, care should be taken when moving these directives within the namespace, to ensure that this is not changing the semantics of the code. As explained above, placing using-alias directives within the namespace element allows the compiler to choose between conflicting types in ways that will not happen when the directives are placed outside of the namespace.
How to Fix Violations
To fix a violation of this rule, move all using directives and using-alias directives within the namespace element.
[StyleCop] SA1201來源 URL： file:///D:/Evernote/SA1201/SA1201.rtf |
TypeName
|
ElementsMustAppearInTheCorrectOrder
|
CheckId
|
SA1201
|
Category
|
Ordering Rules
|
Cause
An element within a C# code file is out of order in relation to the other elements in the code.
Rule Description
A violation of this rule occurs when the code elements within a file do not follow a standard ordering scheme.
To comply with this rule, elements at the file root level or within a namespace must be positioned in the following order:
Extern Alias Directives
Using Directives
Namespaces
Delegates
Enums
Interfaces
Structs
Classes
Within a class, struct, or interface, elements must be positioned in the following order:
Fields
Constructors
Finalizers (Destructors)
Delegates
Events
Enums
Interfaces
Properties
Indexers
Methods
Structs
Classes
Complying with a standard ordering scheme based on element type can increase the readability and maintainability of the file and encourage code reuse.
When implementing an interface, it is sometimes desirable to group all members of the interface next to one another. This will sometimes require violating this rule, if the interface contains elements of different types. This problem can be solved through the use of partial classes.
1. Add the partial attribute to the class, if the class is not already partial.
2. Add a second partial class with the same name. It is possible to place this in the same file, just below the original class, or within a second file.
3. Move the interface inheritance and all members of the interface implementation to the second part of the class.
For example:
/// <summary>
/// Represents a customer of the system.
/// </summary>
public partial class Customer
{
// Contains the main functionality of the class.
}
/// <content>
/// Implements the ICollection class.
/// </content>
public partial class Customer : ICollection
{
public int Count
{
get { return this .count; }
}
public bool IsSynchronized
{
get { return false ; }
}
public object SyncRoot
{
get { return null ; }
}
public void CopyTo(Array array, int index)
{
throw new NotImplementedException ();
}
}
How to Fix Violations
To fix an instance of this violation, order the elements in the file in the order described above.
[StyleCop] SA1400來源 URL： file:///D:/Evernote/SA1400/SA1400.rtf |
TypeName
|
AccessModifierMustBeDeclared
|
CheckId
|
SA1400
|
Category
|
Maintainability Rules
|
Cause
The access modifier for a C# element has not been explicitly defined.
Rule Description
C# allows elements to be defined without an access modifier. Depending upon the type of element, C# will automatically assign an access level to the element in this case.
This rule requires an access modifier to be explicitly defined for every element. This removes the need for the reader to make assumptions about the code, improving the readability of the code.
How to Fix Violations
To fix a violation of this rule, add an access modifier to the declaration of the element.
ex:
private
public
[StyleCop] SA1407來源 URL： file:///D:/Evernote/SA1407/SA1407.rtf |
SA1407: ArithmeticExpressionsMustDeclarePrecedence
|
TypeName
|
ArithmeticExpressionsMustDeclarePrecedence
|
CheckId
|
SA1407
|
Category
|
Maintainability Rules
|
Cause
A C# statement contains a complex arithmetic expression which omits parenthesis around operators.
Rule Description
C# maintains a hierarchy of precedence for arithmetic operators. It is possible in C# to string multiple arithmetic operations together in one statement without wrapping any of the operations in parenthesis, in which case the compiler will automatically set the order and precedence of the operations based on these pre-established rules. For example:
int x = 5 + y * b / 6 % z - 2;
Although this code is legal, it is not highly readable or maintainable. In order to achieve full understanding of this code, the developer must know and understand the basic operator precedence rules in C#.
This rule is intended to increase the readability and maintainability of this type of code, and to reduce the risk of introducing bugs later, by forcing the developer to insert parenthesis to explicitly declare the operator precedence. The example below shows multiple arithmetic operations surrounded by parenthesis:
int x = 5 + (y * ((b / 6) % z)) - 2;
Inserting parenthesis makes the code more obvious and easy to understand, and removes the need for the reader to make assumptions about the code.
How to Fix Violations
To fix a violation of this rule, insert parenthesis within the arithmetic expression to declare the precedence of the operations.
[StyleCop] SA1409來源 URL： file:///D:/Evernote/SA1409/SA1409.rtf |
TypeName
|
RemoveUnnecessaryCode
|
CheckId
|
SA1409
|
Category
|
Maintainability Rules
|
Cause
A C# file contains code which is unnecessary and can be removed without changing the overall logic of the code.
Rule Description
A violation of this rule occurs when the file contains code which can be removed without changing the overall logic of the code.
For example, the following try-catch statement could be removed completely since the try and catch blocks are both empty.
try
{
}
catch (Exception ex)
{
}
The try-finally statement below does contain code within the try block, but it does not contain any catch blocks, and the finally block is empty. Thus, the try-finally is not performing any useful function and can be removed.
try
{
this.Method();
}
finally
{
}
As a final example, the unsafe statement below is empty, and thus provides no value.
unsafe
{
}
How to Fix Violations
The fix a violation of this rule, remove the unnecessary code, or fill in the code with additional statements.
[StyleCop] SA1516來源 URL： file:///D:/Evernote/SA1516/SA1516.rtf |
TypeName
|
ElementsMustBeSeparatedByBlankLine
|
CheckId
|
SA1516
|
Category
|
Layout Rules
|
Cause
Adjacent C# elements are not separated by a blank line.
Rule Description
To improve the readability of the code, StyleCop requires blank lines in certain situations, and prohibits blank lines in other situations. This results in a consistent visual pattern across the code, which can improve recognition and readability of unfamiliar code.
A violation of this rule occurs when two adjacent element are not separated by a blank line. For example:
public void Method1()
{
}
public bool Property
{
get { return true ; }
}
In the example above, the method and property are not separated by a blank line, so a violation of this rule would occur.
public event EventHandler SomeEvent
{
add
{
// add event subscriber here
}
remove
{
// remove event subscriber here
}
}
{
add
{
// add event subscriber here
}
remove
{
// remove event subscriber here
}
}
In the example above, the add and remove of the event need to be separated by a blank line because the add is multiline.
How to Fix Violations>How to Fix Violations
To fix a violation of this rule, add a blank line between the adjacent elements.
[StyleCop] SA1601來源 URL： file:///D:/Evernote/SA1601/SA1601.rtf |
Cause
A C# partial element is missing a documentation header.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs if a partial element (an element with the partial attribute) is completely missing a documentation header, or if the header is empty. In C# the following types of elements can be attributed with the partial attribute: classes, methods.
When documentation is provided on more than one part of the partial class, the documentation for the two classes may be merged together to form a single source of documentation. For example, consider the following two parts of a partial class:
/// <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
{
}
These two different parts of the same partial class each provide different documentation for the class. When the documentation for this class is built into an SDK, the tool building the documentation will either choose to use only one part of the documentation for the class and ignore the other parts, or, in some cases, it may merge the two sources of documentation together, to form a string like: "Documentation for the first part of Class1. Documentation for the second part of Class1."
For these reasons, it can be problematic to provide SDK documentation on more than one part of the partial class. However, it is still advisable to document each part of the class, to increase the readability and maintainability of the code, and StyleCop will require that each part of the class contain header documentation.
This problem is solved through the use of the <content> tag, which can replace the <summary> tag for partial classes. The recommended practice for documenting partial classes is to provide the official SDK documentation for the class on the main part of the partial class. This documentation should be written using the standard <summary> tag. All other parts of the partial class should omit the <summary> tag completely, and replace it with a <content> tag. This allows the developer to document all parts of the partial class while still centralizing all of the official SDK documentation for the class onto one part of the class. The <content> tags will be ignored by the SDK documentation tools.
How to Fix Violations
To fix a violation of this rule, add or fill-in a documentation header for the element.
For example, the following example shows two parts of a partial class, one containing a <summary> header and another containing a <content> header.
/// <summary>
/// Represents a customer in the database.
/// </summary>
public partial class Customer
{
}
/// <content>
/// Contains auto-generated functionality for the Customer class.
/// </content>
public partial class Customer
{
}
<P< P>
[StyleCop] SA1611來源 URL： file:///D:/Evernote/SA1611/SA1611.rtf |
Cause
A C# method, constructor, delegate or indexer element is missing documentation for one or more of its parameters.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs if an element containing parameters is missing documentation for one or more of its parameters.
How to Fix Violations
To fix a violation of this rule, add or fill-in documentation text within a <param> tag for each parameter within the element.
The following example shows a method with a valid documentation header:
/// <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;
}
[StyleCop] SA1618來源 URL： file:///D:/Evernote/SA1618/SA1618.rtf |
TypeName
|
GenericTypeParametersMustBeDocumented
|
CheckId
|
SA1618
|
Category
|
Documentation Rules
|
Cause
A generic C# element is missing documentation for one or more of its generic type parameters.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs if an element containing generic type parameters is missing documentation for one or more of its generic type parameters.
How to Fix Violations
To fix a violation of this rule, add or fill-in documentation text within a <typeparam> tag for each generic type parameter on the element.
The following example shows a method with a valid documentation header:
/// <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>
{
}
[StyleCop] SA1623來源 URL： file:///D:/Evernote/SA1623/SA1623.rtf |
StyleCop 4.5
| |
SA1623: PropertySummaryDocumentationMustMatchAccessors
| |
TypeName
|
PropertySummaryDocumentationMustMatchAccessors
|
CheckId
|
SA1623
|
Category
|
Documentation Rules
|
Cause
The documentation text within a C# property's <summary> tag does not match the accessors within the property.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs if a property's summary documentation does not match the accessors within the property.
The property's summary text must begin with wording describing the types of accessors exposed within the property. If the property contains only a get accessor, the summary must begin with the word "Gets". If the property contains only a set accessor, the summary must begin with the word "Sets". If the property exposes both a get and set accessor, the summary text must begin with "Gets or sets".
For example, consider the following property, which exposes both a get and set accessor. The summary text begins with the words "Gets or sets".
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
public string Name
{
get { return this .name; }
set { this.name = value ; }
}
If the property returns a Boolean value, an additional rule is applied. The summary text for Boolean properties must contain the words "Gets a value indicating whether", "Sets a value indicating whether", or "Gets or sets a value indicating whether". For example, consider the following Boolean property, which only exposes a get accessor:
/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
get { return this .enabled; }
}
In some situations, the set accessor for a property can have more restricted access than the get accessor. For example:
/// <summary>
/// Gets the name of the customer.
/// </summary>
public string Name
{
get { return this .name; }
private set { this .name = value; }
}
In this example, the set accessor has been given private access, meaning that it can only be accessed by local members of the class in which it is contained. The get accessor, however, inherits its access from the parent property, thus it can be accessed by any caller, since the property has public access.
>In this case, the documentation summary text should avoid referring to the set accessor, since it is not visible to external callers.
StyleCop applies a series of rules to determine when the set accessor should be referenced in the property's summary documentation. In general, these rules require the set accessor to be referenced whenever it is visible to the same set of callers as the get accessor, or whenever it is visible to external classes or inheriting classes.
The specific rules for determining whether to include the set accessor in the property's summary documentation are:
1. The set accessor has the same access level as the get accessor. For example:
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
protected string Name
{
get { return this .name; }
set { this .name = value; }
}
2. The property is only internally accessible within the assembly, and the set accessor also has internal access. For example:
internal class Class1
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
protected string Name
{
get { return this .name; }
internal set { this.name = value ; }
}
}
internal class Class1
{
public class Class2
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
public string Name
{
get { return this .name; }
internal set { this.name = value ; }
}
}
}
3. The property is private or is contained beneath a private class, and the set accessor has any access modifier other than private. In the example below, the access modifier declared on the set accessor has no meaning, since the set accessor is contained within a private class and thus cannot be seen by other classes outside of Class1. This effectively gives the set accessor the same access level as the get accessor.
public class Class1
{
private class Class2
{
public class Class3
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
public string Name
{
get { return this .name; }
internal set { this .name = value; }
}
}
}
}
4. Whenever the set accessor has protected or protected internal access, it should be referenced in the documentation. A protected or protected internal set accessor can always been seen by a class inheriting from the class containing the property.
internal class Class1
{
public class Class2
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
internal string Name
{
get { return this .name; }
protected set { this.name = value ; }
}
}
private class Class3 : Class2
{
public Class3(string name) { this.Name = name; }
}
}
How to Fix Violations
To fix a violation of this rule, update the property's summary text so that the description begins with the proper wording, depending upon the type of the property and the types of accessors within the property.
2011 - Andy Reeves
[StyleCop] SA1625來源 URL： file:///D:/Evernote/SA1625/SA1625.rtf |
TypeName
|
ElementDocumentationMustNotBeCopiedAndPasted
|
CheckId
|
SA1625
|
Category
|
Documentation Rules
|
Cause
The Xml documentation for a C# element contains two or more identical entries, indicating that the documentation has been copied and pasted. This can sometimes indicate invalid or poorly written documentation.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs when an element contains two or more identical documentation texts. For example:
/// <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)
{
return firstName + " " + lastName;
}
In some cases, a method may contain one or more parameters which are not used within the body of the method. In this case, the documentation for the parameter can be set to "The parameter is not used." StyleCop will allow multiple parameters to contain identical documentation as long as the documentation string is "The parameter is not used."
How to Fix Violations
To fix a violation of this rule, edit the documentation for the element and ensure that each of the individual documentation texts are unique. For example:
/// <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;
}
How to Suppress Violations
[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1625:ElementDocumentationMustNotBeCopiedAndPasted", Justification = "Reviewed.")]
[StyleCop] SA1630來源 URL： file:///D:/Evernote/SA1630/SA1630.rtf |
TypeName
|
DocumentationTextMustContainWhitespace
|
CheckId
|
SA1630
|
Category
|
Documentation Rules
|
Cause
A section of the Xml header documentation for a C# element does not contain any whitespace between words.
Rule Description
C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: http://msdn.microsoft.com/en-us/magazine/cc302121.aspx.
A violation of this rule occurs when part of the documentation does contain any whitespace between words. This can indicate poorly written or poorly formatted documentation. For example:
/// <summary>
/// Joinsnames
/// </summary>
/// <param name="firstName"> First</param>
/// <param name="lastName"> Last</param>
/// <returns>Name</returns>
public string JoinNames( string firstName, string lastName)
{
...
}
How to Fix Violations
To fix a violation of this rule, ensure that all sections of the documentation contain at least one instance of whitespace between words.
註解跟參數差不多一樣，等於 poor document...
| 從 Evernote 傳送記事 |
留言
張貼留言