Общие соглашения об именовании
Примечание.
Это содержимое перепечатывается разрешением Pearson Education, Inc. из руководства по проектированию платформы: соглашения, идиомы и шаблоны для повторно используемых библиотек .NET, 2-го выпуска. Этот выпуск был опубликован в 2008 году, и книга с тех пор была полностью пересмотрена в третьем выпуске. Некоторые сведения на этой странице могут быть устаревшими.
В этом разделе описаны общие соглашения об именовании, связанные с выбором слов, рекомендации по использованию аббревиатур и акронимов, а также рекомендации по предотвращению использования имен, связанных с конкретным языком.
Выбор слов
✔️ Выбирайте для идентификаторов легко читаемые имена.
Например, свойство с именем 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 | Целое число | int | Int32 |
| uint | UInt32 | unsigned int | UInt32 |
| long | Long | __int64 | Int64 |
| ulong | UInt64 | unsigned __int64 | UInt64 |
| float | Один | float | Один |
| double | Двойной | double | Двойной |
| bool | Boolean | bool | Boolean |
| char | Char | wchar_t | Char |
| string | 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.