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

В этом разделе описаны общие соглашения об именовании, связанные с выбором слова, рекомендации по использованию аббревиатур и акронимов, а так же рекомендации по предотвращению использования имен, зависящих от языка.This section describes general naming conventions that relate to word choice, guidelines on using abbreviations and acronyms, and recommendations on how to avoid using language-specific names.

Вариант выбора словаWord Choice

✔️ выбрать легко читаемые имена идентификаторов.✔️ DO choose easily readable identifier names.

Например, свойство с именем HorizontalAlignment является более английским для чтения, чем AlignmentHorizontal .For example, a property named HorizontalAlignment is more English-readable than AlignmentHorizontal.

✔️ СДЕЛАТЬ предпочтительнее удобочитаемость.✔️ DO favor readability over brevity.

Имя свойства CanScrollHorizontally лучше, чем ScrollableX (Скрытая ссылка на ось X).The property name CanScrollHorizontally is better than ScrollableX (an obscure reference to the X-axis).

❌НЕ используйте знаки подчеркивания, дефисы и другие символы, не являющиеся буквенно-цифровыми.❌ DO NOT use underscores, hyphens, or any other nonalphanumeric characters.

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

❌Избегайте использования идентификаторов, конфликтующих с ключевыми словами широко используемых языков программирования.❌ AVOID using identifiers that conflict with keywords of widely used programming languages.

В соответствии с правилом 4 спецификации CLS, все соответствующие языки должны предоставлять механизм, который разрешает доступ к именованным элементам, использующим ключевое слово этого языка в качестве идентификатора.According to Rule 4 of the Common Language Specification (CLS), all compliant languages must provide a mechanism that allows access to named items that use a keyword of that language as an identifier. Например, в C# в качестве механизма экранирования используется знак @.C#, for example, uses the @ sign as an escape mechanism in this case. Однако рекомендуется избегать часто встречающихся ключевых слов, поскольку гораздо сложнее использовать метод с escape-последовательностью, чем один без него.However, it is still a good idea to avoid common keywords because it is much more difficult to use a method with the escape sequence than one without it.

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

❌НЕ используйте сокращения или соглашения в качестве части имен идентификаторов.❌ DO NOT use abbreviations or contractions as part of identifier names.

Например, используйте GetWindow вместо GetWin .For example, use GetWindow rather than GetWin.

❌НЕ используйте акронимы, которые не являются широко принятыми, и даже если это необходимо.❌ DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary.

Предотвращение имен, зависящих от языкаAvoiding Language-Specific Names

✔️ использовать семантически интересные имена, а не ключевые слова, относящиеся к языку, для имен типов.✔️ DO use semantically interesting names rather than language-specific keywords for type names.

Например, GetLength это лучшее имя, чем GetInt .For example, GetLength is a better name than GetInt.

✔️ использовать универсальное имя типа CLR, а не зависящее от языка имя, в редких случаях, когда идентификатор не имеет семантического значения за пределами его типа.✔️ DO use a generic CLR type name, rather than a language-specific name, in the rare cases when an identifier has no semantic meaning beyond its type.

Например, метод, преобразуя в Int64 , должен иметь ToInt64 имя, а не ToLong (поскольку Int64 является именем CLR для псевдонима, относящегося к C# long ).For example, a method converting to Int64 should be named ToInt64, not ToLong (because Int64 is a CLR name for the C#-specific alias long). В следующей таблице представлены несколько базовых типов данных, использующих имена типов CLR (а также соответствующие имена типов для C#, Visual Basic и C++).The following table presents several base data types using the CLR type names (as well as the corresponding type names for C#, Visual Basic, and C++).

C#C# Visual BasicVisual Basic C++C++ CLRCLR
sbytesbyte SByteSByte charchar SByteSByte
bytebyte ByteByte unsigned charunsigned char ByteByte
shortshort ПромежутокShort shortshort Int16Int16
ushortushort UInt16UInt16 unsigned shortunsigned short UInt16UInt16
intint ЦелоInteger intint Int32Int32
uintuint UInt32UInt32 unsigned intunsigned int UInt32UInt32
longlong LongLong __int64__int64 Int64Int64
ulongulong UInt64UInt64 unsigned __int64unsigned __int64 UInt64UInt64
floatfloat SingleSingle floatfloat SingleSingle
doubledouble DoubleDouble doubledouble DoubleDouble
bool;bool BooleanBoolean bool;bool BooleanBoolean
charchar CharChar wchar_twchar_t CharChar
строкаstring StringString StringString StringString
objectobject ОбъектObject ОбъектObject ОбъектObject

✔️ использовать общее имя, например value или item , вместо повторения имени типа в редких случаях, когда идентификатор не имеет семантического значения, а тип параметра не важен.✔️ DO use a common name, such as value or item, rather than repeating the type name, in the rare cases when an identifier has no semantic meaning and the type of the parameter is not important.

Именование новых версий существующих APINaming New Versions of Existing APIs

При создании новых версий существующего API ✔️ использовать имя, аналогичное старому API.✔️ DO use a name similar to the old API when creating new versions of an existing API.

Это помогает выделить связь между API.This helps to highlight the relationship between the APIs.

✔️ предпочитаете добавлять суффикс, а не префикс, чтобы указать новую версию существующего API.✔️ DO prefer adding a suffix rather than a prefix to indicate a new version of an existing API.

Это поможет обнаружить при просмотре документации или использовании IntelliSense.This will assist discovery when browsing documentation, or using IntelliSense. Старая версия API будет организована ближе к новым интерфейсам API, так как большинство браузеров и IntelliSense отображают идентификаторы в алфавитном порядке.The old version of the API will be organized close to the new APIs, because most browsers and IntelliSense show identifiers in alphabetical order.

✔️ Рассмотрите возможность использования нового, но понятного идентификатора вместо добавления суффикса или префикса.✔️ CONSIDER using a brand new, but meaningful identifier, instead of adding a suffix or a prefix.

✔️ использовать числовой суффикс, чтобы указать новую версию существующего API, особенно если существующее имя API является единственным понятным именем (например, если оно является отраслевым стандартом) и если добавление любого понятного суффикса (или изменение имени) не является соответствующим параметром.✔️ DO use a numeric suffix to indicate a new version of an existing API, particularly if the existing name of the API is the only name that makes sense (i.e., if it is an industry standard) and if adding any meaningful suffix (or changing the name) is not an appropriate option.

❌НЕ используйте суффикс "ex" (или аналогичный) для идентификатора, чтобы отличить его от более ранней версии того же API.❌ DO NOT use the "Ex" (or a similar) suffix for an identifier to distinguish it from an earlier version of the same API.

✔️ использовать суффикс "64" при внедрении версий API, которые работают с 64-битным целым числом (длинное целое число) вместо 32-разрядного целого числа.✔️ DO use the "64" suffix when introducing versions of APIs that operate on a 64-bit integer (a long integer) instead of a 32-bit integer. Этот подход следует применять только в том случае, если существующий 32-разрядный API существует. не Выменяйте его для новых API-интерфейсов, используя только 64 разрядную версию.You only need to take this approach when the existing 32-bit API exists; don't do it for brand new APIs with only a 64-bit version.

Части © 2005, 2009 Корпорация Майкрософт. Все права защищены.Portions © 2005, 2009 Microsoft Corporation. All rights reserved.

Перепечатано с разрешения Pearson Education, Inc. из книги Инфраструктура программных проектов. Соглашения, идиомы и шаблоны для многократно используемых библиотек .NET (2-е издание), авторы: Кржиштоф Цвалина (Krzysztof Cwalina) и Брэд Абрамс (Brad Abrams). Книга опубликована 22 октября 2008 г. издательством Addison-Wesley Professional в рамках серии, посвященной разработке для Microsoft Windows.Reprinted by permission of Pearson Education, Inc. from Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition by Krzysztof Cwalina and Brad Abrams, published Oct 22, 2008 by Addison-Wesley Professional as part of the Microsoft Windows Development Series.

См. такжеSee also