День двести восьмой. #BestPractices
Советы по разработке типов
6. Разработка перечислений. Начало
Перечисления - это особый значимый тип.
Виды перечислений:
- Простые - небольшие замкнутые наборы вариантов (например, набор цветов).
- Битовые флаги - предназначены для поддержки побитовых операций над значениями (например, список опций).
✅ ИСПОЛЬЗУЙТЕ существительные в единственном числе для простых перечислений и во множественном для битовых флагов.
❌ ИЗБЕГАЙТЕ наследования от
✅ ИСПОЛЬЗУЙТЕ перечисление для строгого ввода параметров, свойств и возвращаемых значений, представляющих наборы значений.
✅ ИСПОЛЬЗУЙТЕ перечисление вместо статических констант.
❌ ИЗБЕГАЙТЕ использования перечислений для открытых наборов (таких как версии операционной системы, имена ваших друзей и т.д.).
❌ ИЗБЕГАЙТЕ создания зарезервированных значений перечисления, которые предназначены для будущего использования. Вы всегда можете просто добавить значения к существующему перечислению на более позднем этапе. Зарезервированные значения просто загрязняют набор реальных значений и приводят к ошибкам при использовании.
❌ ИЗБЕГАЙТЕ создания перечисления только с одним значением. Обычной практикой обеспечения будущей расширяемости API является добавление зарезервированных параметров в сигнатуры методов. Такие зарезервированные параметры могут быть выражены в виде перечисления с одним значением по умолчанию. Это неверная практика для управляемых API. Перегрузка метода позволяет добавлять параметры в будущих выпусках.
❌ ИЗБЕГАЙТЕ включения сервисных значений в перечисления. Несмотря на то, что они иногда полезны для разработчиков фреймворка, сервисные значения сбивают с толку его пользователей. Они используются для отслеживания состояния перечисления, а не являются одним из значений из набора, представляемого перечислением.
✅ ИСПОЛЬЗУЙТЕ нулевое значение для простых перечислений. Вы можете назвать это значение «None» («Значение отсутствует»). Если такое значение не подходит для данного конкретного перечисления, наиболее распространенному значению по умолчанию для перечисления должно быть присвоено базовое значение ноль.
⚠️ РАССМОТРИТЕ использование Int32 (по умолчанию в большинстве языков) в качестве базового типа перечисления, если не выполняется одно из следующих условий:
- Перечисление представляет собой битовые флаги, и у вас более 32 флагов или вы ожидаете, что их будет больше в будущем.
- Базовый тип отличается от Int32 для облегчения взаимодействия с неуправляемым кодом, ожидающим перечисления разных размеров.
- Меньший по размеру базовый тип приведёт к значительной экономии места. Если вы ожидаете, что перечисление будет использоваться главным образом в качестве аргумента в логике кода, размер не имеет большого значения. Экономия по размеру может быть значительной, если ожидается, что:
- перечисление будет использоваться как поле в очень часто создаваемой структуре или классе.
- пользователи будут создавать большие массивы или коллекции экземпляров перечисления.
- большое количество экземпляров перечисления будет сериализовываться.
Продолжение следует…
Источник: https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/
Советы по разработке типов
6. Разработка перечислений. Начало
Перечисления - это особый значимый тип.
Виды перечислений:
- Простые - небольшие замкнутые наборы вариантов (например, набор цветов).
- Битовые флаги - предназначены для поддержки побитовых операций над значениями (например, список опций).
✅ ИСПОЛЬЗУЙТЕ существительные в единственном числе для простых перечислений и во множественном для битовых флагов.
❌ ИЗБЕГАЙТЕ наследования от
System.Enum напрямую. System.Enum - это специальный тип, используемый CLR для создания пользовательских перечислений. Большинство языков программирования предоставляют специальный элемент, который дает вам доступ к этой функциональности. В C# для определения перечисления используется ключевое слово enum.✅ ИСПОЛЬЗУЙТЕ перечисление для строгого ввода параметров, свойств и возвращаемых значений, представляющих наборы значений.
✅ ИСПОЛЬЗУЙТЕ перечисление вместо статических констант.
❌ ИЗБЕГАЙТЕ использования перечислений для открытых наборов (таких как версии операционной системы, имена ваших друзей и т.д.).
❌ ИЗБЕГАЙТЕ создания зарезервированных значений перечисления, которые предназначены для будущего использования. Вы всегда можете просто добавить значения к существующему перечислению на более позднем этапе. Зарезервированные значения просто загрязняют набор реальных значений и приводят к ошибкам при использовании.
❌ ИЗБЕГАЙТЕ создания перечисления только с одним значением. Обычной практикой обеспечения будущей расширяемости API является добавление зарезервированных параметров в сигнатуры методов. Такие зарезервированные параметры могут быть выражены в виде перечисления с одним значением по умолчанию. Это неверная практика для управляемых API. Перегрузка метода позволяет добавлять параметры в будущих выпусках.
❌ ИЗБЕГАЙТЕ включения сервисных значений в перечисления. Несмотря на то, что они иногда полезны для разработчиков фреймворка, сервисные значения сбивают с толку его пользователей. Они используются для отслеживания состояния перечисления, а не являются одним из значений из набора, представляемого перечислением.
✅ ИСПОЛЬЗУЙТЕ нулевое значение для простых перечислений. Вы можете назвать это значение «None» («Значение отсутствует»). Если такое значение не подходит для данного конкретного перечисления, наиболее распространенному значению по умолчанию для перечисления должно быть присвоено базовое значение ноль.
⚠️ РАССМОТРИТЕ использование Int32 (по умолчанию в большинстве языков) в качестве базового типа перечисления, если не выполняется одно из следующих условий:
- Перечисление представляет собой битовые флаги, и у вас более 32 флагов или вы ожидаете, что их будет больше в будущем.
- Базовый тип отличается от Int32 для облегчения взаимодействия с неуправляемым кодом, ожидающим перечисления разных размеров.
- Меньший по размеру базовый тип приведёт к значительной экономии места. Если вы ожидаете, что перечисление будет использоваться главным образом в качестве аргумента в логике кода, размер не имеет большого значения. Экономия по размеру может быть значительной, если ожидается, что:
- перечисление будет использоваться как поле в очень часто создаваемой структуре или классе.
- пользователи будут создавать большие массивы или коллекции экземпляров перечисления.
- большое количество экземпляров перечисления будет сериализовываться.
Продолжение следует…
Источник: https://docs.microsoft.com/en-us/dotnet/standard/design-guidelines/