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

Значение
Идентификатор правила CA1710
Категория Именование
Исправление является критическим или не критическим Критическое

Причина

В идентификаторе отсутствует правильный суффикс.

По умолчанию это правило проверяет только видимые извне идентификаторы, но это поведение можно настроить.

Описание правила

По соглашению имена типов, расширяющих определенные базовые типы или реализующих определенные интерфейсы, а также типов, являющихся производными от первых, имеют суффикс, связанный с базовым типом или интерфейсом.

Соглашения об именовании обеспечивают единство вида библиотек, предназначенных для среды CLR. Это сокращает время, необходимое для изучения новых библиотек программного обеспечения, и позволяет клиентам увериться в том, что разработчик библиотеки имеет опыт разработки управляемого кода.

В следующей таблице перечислены базовые типы и интерфейсы, имеющие связанные суффиксы.

Базовый тип или интерфейс Суффикс
System.Attribute attribute
System.EventArgs EventArgs
System.Exception Исключение
System.Collections.ICollection Коллекция
System.Collections.IDictionary Словарь
System.Collections.IEnumerable Коллекция
System.Collections.Generic.IReadOnlyDictionary<TKey,TValue> Словарь
System.Collections.Queue Коллекция или очередь
System.Collections.Stack Коллекция или стек
System.Collections.Generic.ICollection<T> Коллекция
System.Collections.Generic.IDictionary<TKey,TValue> Словарь
System.Data.DataSet DataSet
System.Data.DataTable Коллекция или DataTable
System.IO.Stream Stream
System.Security.IPermission Разрешение
System.Security.Policy.IMembershipCondition Условие
Делегат обработчика событий. 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.

Для других суффиксов не следует отключать предупреждение из этого правила. Суффикс позволяет понять предполагаемое использование из имени типа.

Настройка кода для анализа

Используйте следующие параметры, чтобы указать части базы кода, к которым будет применяться это правило.

Эти параметры можно настроить только для указанного правила, для всех правил или для всех правил в этой категории (именование). Дополнительные сведения см. в статье Параметры конфигурации правила качества кода.

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

См. также раздел