CA1710: идентификаторы должны иметь правильные суффиксы
| Свойство | Значение |
|---|---|
| Идентификатор правила | CA1710 |
| Заголовок | Идентификаторы должны иметь правильные суффиксы |
| Категория | Именование |
| Исправление является критическим или не критическим | Критическое |
| Включен по умолчанию в .NET 9 | No |
Причина
В идентификаторе отсутствует правильный суффикс.
По умолчанию это правило проверяет только видимые извне идентификаторы, но это поведение можно настроить.
Описание правила
По соглашению имена типов, расширяющих определенные базовые типы или реализующих определенные интерфейсы, а также типов, являющихся производными от первых, имеют суффикс, связанный с базовым типом или интерфейсом.
Соглашения об именовании обеспечивают единство вида библиотек, предназначенных для среды CLR. Это сокращает время, необходимое для изучения новых библиотек программного обеспечения, и позволяет клиентам увериться в том, что разработчик библиотеки имеет опыт разработки управляемого кода.
В следующей таблице перечислены базовые типы и интерфейсы, имеющие связанные суффиксы.
| Базовый тип или интерфейс | Суффикс |
|---|---|
| System.Attribute | Атрибут |
| System.EventArgs | EventArgs |
| System.Exception | Исключение |
| System.Collections.ICollection | Коллекция |
| System.Collections.IDictionary | Dictionary |
| System.Collections.IEnumerable | Коллекция |
| System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> | Dictionary |
| System.Collections.Queue | Коллекция или очередь |
| System.Collections.Stack | Коллекция или стек |
| System.Collections.Generic.ICollection<T> | Коллекция |
| System.Collections.Generic.IDictionary<TKey,TValue> | Dictionary |
| System.Data.DataSet | Набор данных |
| System.Data.DataTable | Коллекция или DataTable |
| System.IO.Stream | Stream |
| System.Security.IPermission | Разрешение |
| System.Security.Policy.IMembershipCondition | Condition |
| Делегат обработчика событий. | EventHandler |
Для типов, реализующих ICollection и являющихся обобщенными типами структуры данных, таких как словарь, стек или очередь, допускаются имена, которые предоставляют значимую информацию о предполагаемом использовании типа.
Имена типов, реализующих ICollection и являющихся коллекцией определенных элементов, заканчиваются суффиксом "Collection". Например, коллекция объектов Queue будет иметь имя "QueueCollection". Суффикс "Collection" означает, что элементы коллекции можно перечислить с помощью инструкции foreach (For Each в Visual Basic).
Имена типов, реализующих IDictionary или IReadOnlyDictionary<TKey,TValue>, заканчиваются суффиксом "Dictionary", даже если этот тип реализует также IEnumerable или ICollection. Соглашения об именовании, касающиеся суффиксов "Collection" и "Dictionary", помогают пользователям различать следующие два шаблона перечисления.
Типы с суффиксом "Collection" следуют этому шаблону перечисления.
foreach(SomeType x in SomeCollection) { }
Типы с суффиксом "Dictionary" следуют этому шаблону перечисления.
foreach(SomeType x in SomeDictionary.Values) { }
В объект DataSet входит коллекция объектов DataTable, которая, в свою очередь, содержит среди прочих коллекции объектов System.Data.DataColumn и System.Data.DataRow. Эти коллекции реализуют ICollection посредством базового класса System.Data.InternalDataCollectionBase.
Устранение нарушений
Переименуйте тип так, чтобы он заканчивался правильным термином.
Когда лучше отключить предупреждения
Можно спокойно отключить предупреждение об использовании суффикса "Collection", если тип является обобщенной структурой данных, которая может быть расширена, или которая будет содержать произвольный набор различных элементов. В таком случае имя, предоставляющее значимую информацию о применении, производительности или других характеристиках структуры данных, может быть осмысленным (например, BinaryTree). В случаях, когда тип представляет коллекцию определенного типа (например, StringCollection), не следует отключать предупреждение из этого правила, так как суффикс указывает, что этот тип может быть перечислен с помощью инструкции foreach.
Для других суффиксов не следует отключать предупреждение из этого правила. Суффикс позволяет понять предполагаемое использование из имени типа.
Отключение предупреждений
Если вы просто хотите отключить одно нарушение, добавьте директивы препроцессора в исходный файл, чтобы отключить и повторно включить правило.
#pragma warning disable CA1710
// The code that's violating the rule is on this line.
#pragma warning restore CA1710
Чтобы отключить правило для файла, папки или проекта, задайте его серьезность none в файле конфигурации.
[*.{cs,vb}]
dotnet_diagnostic.CA1710.severity = none
Дополнительные сведения см. в разделе Практическое руководство. Скрытие предупреждений анализа кода.
Настройка кода для анализа
Используйте следующие параметры, чтобы указать части базы кода, к которым будет применяться это правило.
- Включение определенных контактных зон API
- Исключить косвенные базовые типы
- Дополнительные обязательные суффиксы
Эти параметры можно настроить только для этого правила, для всех правил, к которым она применяется, или для всех правил в этой категории (именование), к которым она применяется. Дополнительные сведения см. в статье Параметры конфигурации правила качества кода.
Включение определенных контактных зон API
Вы можете настроить, для каких частей базы кода следует выполнять это правило в зависимости от их доступности. Например, чтобы указать, что правило должно выполняться только для закрытой контактной зоны API, добавьте следующую пару "ключ-значение" в файл EDITORCONFIG в своем проекте:
dotnet_code_quality.CAXXXX.api_surface = private, internal
Исключить косвенные базовые типы
Вы можете указать, следует ли исключать из правила косвенные базовые типы. По умолчанию этот параметр имеет значение true, что означает, что анализ ограничен текущим базовым типом.
dotnet_code_quality.CA1710.exclude_indirect_base_types = false
Дополнительные обязательные суффиксы
Вы можете указать дополнительные обязательные суффиксы или переопределить поведение некоторых жестко заданных суффиксов, добавив следующую пару "ключ-значение" в файл с расширением .editorconfig в своем проекте:
dotnet_code_quality.CA1710.additional_required_suffixes = [type]->[suffix]
Для разделения значений используйте символ |. Типы можно указывать в одном из следующих форматов:
- Только имя типа (включает все типы с этим именем, любого типа и в любом пространстве имен).
- Полные имена в формате идентификатора документации для символа с необязательным префиксом
T:.
Примеры:
| Значение параметра | Итоги |
|---|---|
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class |
Все типы, наследующие от "MyClass", должны иметь суффикс "Class". |
dotnet_code_quality.CA1710.additional_required_suffixes = MyClass->Class|MyNamespace.IPath->Path |
Все типы, наследующие от "MyClass", должны иметь суффикс "Class", и все типы, реализующие "MyNamespace.IPath", должны иметь суффикс "Path". |
dotnet_code_quality.CA1710.additional_required_suffixes = T:System.Data.IDataReader->{} |
Переопределяет встроенные суффиксы. В данном случае все типы, реализующие "IDataReader", больше не обязаны иметь суффикс "Collection". |
Связанные правила
CA1711: идентификаторы не должны иметь неверных суффиксов
