Общие соглашения об именовании

В этом разделе описаны общие соглашения об именовании, связанные с выбором слов, рекомендации по использованию аббревиатур и акронимов, а также рекомендации по предотвращению использования имен, связанных с конкретным языком.

Выбор слов

✔️ Выбирайте для идентификаторов легко читаемые имена.

Например, свойство с именем HorizontalAlignment легче читается на английском, чем AlignmentHorizontal.

✔️ Удобочитаемость важнее краткости.

Имя свойства CanScrollHorizontally лучше, чем ScrollableX (неочевидная ссылка на ось X).

❌ НЕ используйте знаки подчеркивания, дефисы и другие символы, не являющиеся буквенно-цифровыми.

❌ НЕ используйте венгерскую нотацию.

❌ ИЗБЕГАЙТЕ использования идентификаторов, совпадающих с ключевыми словами широко используемых языков программирования.

В соответствии с правилом 4 спецификации CLS все соответствующие языки должны предоставлять механизм, который разрешает доступ к именованным элементам, использующим ключевое слово этого языка в качестве идентификатора. Например, в C# в качестве escape-символа используется @. Однако рекомендуется избегать часто встречающихся ключевых слов, поскольку гораздо сложнее использовать метод с escape-последовательностью, чем без нее.

Использование сокращений и акронимов

❌ НЕ используйте сокращения в именах идентификаторов.

Например, используйте GetWindow, а не GetWin.

❌ НЕ используйте акронимы, которые не являются широко принятыми, и в целом используется акронимы только при необходимости.

Предотвращение использования имен, связанных с конкретным языком

✔️ Для имен типов используйте семантически содержательные имена, а не ключевые слова, относящиеся к конкретному языку.

Например, имя GetLength лучшее, чем GetInt.

✔️ Используйте универсальное имя типа CLR, а не относящееся к конкретному языку имя, в редких случаях, когда у идентификатора нет семантического значения, кроме его типа.

Например, у метода, преобразующего в Int64, должно быть имя ToInt64, а не ToLong (поскольку Int64 является именем CLR для относящегося к C# псевдонима long). В таблице ниже представлено несколько базовых типов данных, использующих имена типов CLR (а также соответствующие имена типов для C#, Visual Basic и C++).

C# Visual Basic C++ CLR
sbyte SByte char SByte
byte Byte unsigned char Byte
short Short short Int16
ushort UInt16 unsigned short UInt16
int Integer int Int32
uint UInt32 unsigned int UInt32
long Long __int64 Int64
ulong UInt64 unsigned __int64 UInt64
float Single float Single
double Double double Double
bool Boolean bool Boolean
char Char wchar_t Char
строка String String String
object Объект Объект Объект

✔️ Используйте общее имя, например value или item, вместо повторения имени типа в редких случаях, когда идентификатор не имеет семантического значения и тип параметра не имеет значения.

Именование новых версий существующих API

✔️ При создании новых версий существующего API используйте имя, аналогичное старому API.

Это помогает подчеркнуть связь между API.

✔️ Чтобы указать новую версию существующего API, желательно добавлять суффикс, а не префикс.

Это поможет найти нужную информацию при просмотре документации или использовании IntelliSense. Старая версия API будет находиться близко к новым версиям API, так как большинство браузеров и IntelliSense отображают идентификаторы в алфавитном порядке.

✔️ Используйте новый, но понятный идентификатор вместо добавления суффикса или префикса.

✔️ Используйте числовой суффикс, чтобы указать новую версию существующего API, особенно если существующее имя API является единственным понятным именем (например, если оно является отраслевым стандартом) и если добавление любого понятного суффикса (или изменение имени) не представляется возможным.

❌ НЕ используйте суффикс "Ex" (или аналогичный), чтобы отличать идентификатор его от более ранней версии того же API.

✔️ Используйте суффикс "64" при внедрении версий API, которые работают с 64-разрядными целыми числами (длинное целое число), а не с 32-разрядными целыми числами. Этот подход следует применять только в том случае, если существует 32-разрядный API. Не используйте его для новых API, у которых есть только 64-разрядная версия.

Фрагменты: © Корпорация Майкрософт (Microsoft Corporation), 2005, 2009. Все права защищены.

Перепечатано с разрешения Pearson Education, Inc. из книги Инфраструктура программных проектов. Соглашения, идиомы и шаблоны для многократно используемых библиотек .NET (2-е издание), авторы: Кржиштоф Цвалина (Krzysztof Cwalina) и Брэд Абрамс (Brad Abrams). Книга опубликована 22 октября 2008 г. издательством Addison-Wesley Professional в рамках серии, посвященной разработке для Microsoft Windows.

См. также