CA1710: идентификаторы должны иметь правильные суффиксы

  • Статья
Свойство Значение
Идентификатор правила CA1710
Заголовок Идентификаторы должны иметь правильные суффиксы
Категория Именование
Исправление является критическим или не критическим Критическое
Включен по умолчанию в .NET 8 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, добавьте следующую пару "ключ-значение" в файл 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]

Для разделения значений используйте символ |. Типы можно указывать в одном из следующих форматов:

Примеры:

Значение параметра Итоги
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: идентификаторы не должны иметь неверных суффиксов

См. также