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

В этом разделе описаны общие соглашения об именовании, связанные с выбором word, инструкции по использованию сокращений и акронимов и рекомендации о том, как избежать использования имен конкретного языка.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 выберите легко читаемые имена идентификаторов.✓ DO choose easily readable identifier names.

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

✓ DO предпочтение краткости удобочитаемости.✓ DO favor readability over brevity.

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

X DO NOT использовать другие символы, дефисы и знаки подчеркивания.X DO NOT use underscores, hyphens, or any other nonalphanumeric characters.

X DO NOT венгерская нотация.X DO NOT use Hungarian notation.

X AVOID использования идентификаторов, совпадающих с ключевыми словами, широко используемые языки программирования.X 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#, например, используется знак как механизм escape, в данном случае @.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

X DO NOT использовать аббревиатуры или сокращения как часть имени идентификатора.X DO NOT use abbreviations or contractions as part of identifier names.

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

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

Как избежать именаAvoiding Language-Specific Names

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

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

✓ DO использовать имя универсального типа 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 ShortShort shortshort Int16Int16
ushortushort UInt16UInt16 unsigned shortunsigned short UInt16UInt16
intint IntegerInteger 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
boolbool BooleanBoolean boolbool BooleanBoolean
charchar CharChar wchar_twchar_t CharChar
stringstring StringString StringString StringString
objectobject ОбъектObject ОбъектObject ОбъектObject

✓ DO использовать общее имя, например 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

✓ DO использовать аналогичный 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.

✓ DO предпочтение Добавление суффикса вместо префикса для указания новой версии существующего 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 с помощью идентификатора совершенно новый, но может применяться, вместо добавления суффикса и префикса.✓ CONSIDER using a brand new, but meaningful identifier, instead of adding a suffix or a prefix.

✓ DO Используйте числовой суффикс для указания новой версии существующего API, особенно в том случае, если имя существующего API-интерфейса только имя, которое имеет смысл (т. е. Если это отраслевой стандарт) и при добавлении любое значимое суффикс (или изменить имя) не приложения параметр ropriate.✓ 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.

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

✓ DO используйте суффикс «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.

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

Перепечатано разрешением Пирсона для образовательных учреждений, Inc. из рекомендации по разработке Framework: Условные обозначения, стили и шаблоны для библиотеки .NET для повторного использования, 2nd Edition Кшиштов Квалина и Брэд Абрамс, опубликованных 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