Property Headers

By default StyleCop comes with two rules which govern the summary documentation for properties, depending upon the types of accessors contained with the property. For example:

/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
public string Name
{
get;
set;
}

In this example, StyleCop will require that the summary text starts with “Gets or sets” since the property has visible get and set accessors. In some cases, the set accessor has more limited access than the get accessor. For example:

/// <summary>
/// Gets the name of the customer.
/// </summary>
public string Name
{
get;
private set;
}

In this case, StyleCop requires the summary documentation to omit the “or sets” wording since public consumers of the property can only see the get accessor.

Unfortunately, it can sometimes be non-obvious whether the set accessor within a property is actually less accessible than the get accessor. For example, consider the case where a public property is contained within an internal class, and the set accessor has the internal keyword. In effect, both the get and set accessors have the same access level, because the entire class is internal. In this case, the summary documentation should refer to both the get and set accessors, since they have the same access level and can both be viewed by the same set of callers.

This can be a little confusing. In StyleCop 4.3.2, this behavior of this rule has changed slightly to avoid some confusion about when the “or sets” wording should be included. StyleCop now 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;
set;
}

2. The property is only internally accessible within the assembly, and the set accessor also has the internal keyword. For example:

internal class Class1
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
protected string Name
{
get;
internal set;
}
}

internal class Class2
{
public class Class3
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
public string Name
{
get;
internal set;
}
}
}

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;
internal set;
}
}
}
}

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 be seen by an inheriting class, thus it should be included within the documentation. In the example below, the property is internal because it is contained within an internal class. However, the set accessor is protected, meaning that it can be seen by an inheriting class. The constructor of Class3 sets the value of the Name property. Thus, the property header should still refer to the set accessor.

internal class Class1
{
public class Class2
{
/// <summary>
/// Gets or sets the name of the customer.
/// </summary>
public string Name
{
get;
protected set;
}
}

    private class Class3 : Class2
{
public Class3(string name)
{
this.Name = name;
}
}
}