-
Notifications
You must be signed in to change notification settings - Fork 5.9k
/
ca1710.md
157 lines (110 loc) · 9.47 KB
/
ca1710.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
---
title: "CA1710: Identifiers should have correct suffix (code analysis)"
description: "Learn about code analysis rule CA1710: Identifiers should have correct suffix"
ms.date: 06/11/2020
f1_keywords:
- CA1710
- IdentifiersShouldHaveCorrectSuffix
helpviewer_keywords:
- IdentifiersShouldHaveCorrectSuffix
- CA1710
author: gewarren
ms.author: gewarren
---
# CA1710: Identifiers should have correct suffix
| Property | Value |
|-------------------------------------|----------------------------------------|
| **Rule ID** | CA1710 |
| **Title** | Identifiers should have correct suffix |
| **Category** | [Naming](naming-warnings.md) |
| **Fix is breaking or non-breaking** | Breaking |
| **Enabled by default in .NET 8** | No |
## Cause
An identifier does not have the correct suffix.
By default, this rule only looks at externally visible identifiers, but this is [configurable](#configure-code-to-analyze).
## Rule description
By convention, the names of types that extend certain base types or that implement certain interfaces, or types derived from these types, have a suffix that is associated with the base type or interface.
Naming conventions provide a common look for libraries that target the common language runtime. This reduces the learning curve that is required for new software libraries, and increases customer confidence that the library was developed by someone who has expertise in developing managed code.
The following table lists the base types and interfaces that have associated suffixes.
| Base type/Interface | Suffix |
| ---------------------------------------------------------------------------------- | ----------------------- |
| <xref:System.Attribute?displayProperty=fullName> | Attribute |
| <xref:System.EventArgs?displayProperty=fullName> | EventArgs |
| <xref:System.Exception?displayProperty=fullName> | Exception |
| <xref:System.Collections.ICollection?displayProperty=fullName> | Collection |
| <xref:System.Collections.IDictionary?displayProperty=fullName> | Dictionary |
| <xref:System.Collections.IEnumerable?displayProperty=fullName> | Collection |
| <xref:System.Collections.Generic.IReadOnlyDictionary%602?displayProperty=fullName> | Dictionary |
| <xref:System.Collections.Queue?displayProperty=fullName> | Collection or Queue |
| <xref:System.Collections.Stack?displayProperty=fullName> | Collection or Stack |
| <xref:System.Collections.Generic.ICollection%601?displayProperty=fullName> | Collection |
| <xref:System.Collections.Generic.IDictionary%602?displayProperty=fullName> | Dictionary |
| <xref:System.Data.DataSet?displayProperty=fullName> | DataSet |
| <xref:System.Data.DataTable?displayProperty=fullName> | Collection or DataTable |
| <xref:System.IO.Stream?displayProperty=fullName> | Stream |
| <xref:System.Security.IPermission?displayProperty=fullName> | Permission |
| <xref:System.Security.Policy.IMembershipCondition?displayProperty=fullName> | Condition |
| An event-handler delegate. | EventHandler |
Types that implement <xref:System.Collections.ICollection> and are a generalized type of data structure, such as a dictionary, stack, or queue, are allowed names that provide meaningful information about the intended usage of the type.
Types that implement <xref:System.Collections.ICollection> and are a collection of specific items have names that end with the word 'Collection'. For example, a collection of <xref:System.Collections.Queue> objects would have the name 'QueueCollection'. The 'Collection' suffix signifies that the members of the collection can be enumerated by using the `foreach` (`For Each` in Visual Basic) statement.
Types that implement <xref:System.Collections.IDictionary> or <xref:System.Collections.Generic.IReadOnlyDictionary%602> have names that end with the word 'Dictionary' even if the type also implements <xref:System.Collections.IEnumerable> or <xref:System.Collections.ICollection>. The 'Collection' and 'Dictionary' suffix naming conventions enable users to distinguish between the following two enumeration patterns.
Types with the 'Collection' suffix follow this enumeration pattern.
```csharp
foreach(SomeType x in SomeCollection) { }
```
Types with the 'Dictionary' suffix follow this enumeration pattern.
```csharp
foreach(SomeType x in SomeDictionary.Values) { }
```
A <xref:System.Data.DataSet> object consists of a collection of <xref:System.Data.DataTable> objects, which consist of collections of <xref:System.Data.DataColumn?displayProperty=fullName> and <xref:System.Data.DataRow?displayProperty=fullName> objects, among others. These collections implement <xref:System.Collections.ICollection> through the base <xref:System.Data.InternalDataCollectionBase?displayProperty=fullName> class.
## How to fix violations
Rename the type so that it is suffixed with the correct term.
## When to suppress warnings
It is safe to suppress a warning to use the 'Collection' suffix if the type is a generalized data structure that might be extended or that will hold an arbitrary set of diverse items. In this case, a name that provides meaningful information about the implementation, performance, or other characteristics of the data structure might make sense (for example, BinaryTree). In cases where the type represents a collection of a specific type (for example, StringCollection), do not suppress a warning from this rule because the suffix indicates that the type can be enumerated by using a `foreach` statement.
For other suffixes, do not suppress a warning from this rule. The suffix allows the intended usage to be evident from the type name.
## Suppress a warning
If you just want to suppress a single violation, add preprocessor directives to your source file to disable and then re-enable the rule.
```csharp
#pragma warning disable CA1710
// The code that's violating the rule is on this line.
#pragma warning restore CA1710
```
To disable the rule for a file, folder, or project, set its severity to `none` in the [configuration file](../configuration-files.md).
```ini
[*.{cs,vb}]
dotnet_diagnostic.CA1710.severity = none
```
For more information, see [How to suppress code analysis warnings](../suppress-warnings.md).
## Configure code to analyze
Use the following options to configure which parts of your codebase to run this rule on.
- [Include specific API surfaces](#include-specific-api-surfaces)
- [Exclude indirect base types](#exclude-indirect-base-types)
- [Additional required suffixes](#additional-required-suffixes)
You can configure these options for just this rule, for all rules it applies to, or for all rules in this category ([Naming](naming-warnings.md)) that it applies to. For more information, see [Code quality rule configuration options](../code-quality-rule-options.md).
[!INCLUDE[api-surface](../includes/api-surface.md)]
### Exclude indirect base types
You can configure whether to exclude indirect base types from the rule. By default, this option is set to true, which restricts analysis to the current base type.
```ini
dotnet_code_quality.CA1710.exclude_indirect_base_types = false
```
### Additional required suffixes
You can provide additional required suffixes or override the behavior of some hardcoded suffixes by adding the following key-value pair to an *.editorconfig* file in your project:
```ini
dotnet_code_quality.CA1710.additional_required_suffixes = [type]->[suffix]
```
Separate multiple values with a `|` character. Types can be specified in either of the following formats:
- Type name only (includes all types with the name, regardless of the containing type or namespace).
- Fully qualified names in the symbol's [documentation ID format](../../../csharp/language-reference/xmldoc/index.md#id-strings) with an optional `T:` prefix.
Examples:
<!-- markdownlint-disable MD056 -->
| Option Value | Summary |
| --- | --- |
|`dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class` | All types that inherit from 'MyClass' are required to have the 'Class' suffix. |
|`dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class|MyNamespace.IPath->Path` | All types that inherit from 'MyClass' are required to have the 'Class' suffix AND all types that implement 'MyNamespace.IPath' are required to have the 'Path' suffix. |
|`dotnet_code_quality.CA1710.additional_required_suffixes = T:System.Data.IDataReader->{}` | Overrides built-in suffixes. In this case, all types that implement 'IDataReader' are no longer required to end in 'Collection'. |
<!-- markdownlint-enable MD056 -->
## Related rules
[CA1711: Identifiers should not have incorrect suffix](ca1711.md)
## See also
- [Attributes](../../../standard/design-guidelines/attributes.md)
- [Handling and raising events](../../../standard/events/index.md)