Convenções de nomenclatura geraisGeneral Naming Conventions

Esta seção descreve as convenções de nomenclatura gerais relacionadas à escolha do Word, diretrizes sobre como usar abreviações e acrônimos e recomendações sobre como evitar o uso de nomes específicos à linguagem.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.

Opção de palavraWord Choice

✔️ Escolha nomes de identificadores facilmente legíveis.✔️ DO choose easily readable identifier names.

Por exemplo, uma propriedade chamada HorizontalAlignment é mais legível do que AlignmentHorizontal .For example, a property named HorizontalAlignment is more English-readable than AlignmentHorizontal.

✔️ favorecer a legibilidade em breve.✔️ DO favor readability over brevity.

O nome da propriedade CanScrollHorizontally é melhor do que ScrollableX (uma referência obscura para o eixo X).The property name CanScrollHorizontally is better than ScrollableX (an obscure reference to the X-axis).

❌Não use sublinhados, hifens ou quaisquer outros caracteres não alfanuméricos.❌ DO NOT use underscores, hyphens, or any other nonalphanumeric characters.

❌Não use a notação húngara.❌ DO NOT use Hungarian notation.

❌Evite usar identificadores que entrem em conflito com palavras-chave de linguagens de programação amplamente usadas.❌ AVOID using identifiers that conflict with keywords of widely used programming languages.

De acordo com a regra 4 do Common Language Specification (CLS), todos os idiomas compatíveis devem fornecer um mecanismo que permita o acesso a itens nomeados que usam uma palavra-chave desse idioma como um identificador.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. O C#, por exemplo, usa o sinal @ como um mecanismo de escape nesse caso.C#, for example, uses the @ sign as an escape mechanism in this case. No entanto, ainda é uma boa ideia evitar palavras-chave comuns, pois é muito mais difícil usar um método com a sequência de escape de um sem ele.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.

Usando abreviações e acrônimosUsing Abbreviations and Acronyms

❌Não use abreviações ou contratações como parte dos nomes de identificador.❌ DO NOT use abbreviations or contractions as part of identifier names.

Por exemplo, use GetWindow em vez de GetWin .For example, use GetWindow rather than GetWin.

❌Não use nenhum acrônimo que não seja amplamente aceito e, mesmo que eles estejam, somente quando necessário.❌ DO NOT use any acronyms that are not widely accepted, and even if they are, only when necessary.

Evitando nomes específicos de idiomaAvoiding Language-Specific Names

✔️ usam nomes semanticamente interessantes em vez de palavras-chave específicas de idioma para nomes de tipos.✔️ DO use semantically interesting names rather than language-specific keywords for type names.

Por exemplo, GetLength é um nome melhor do que GetInt .For example, GetLength is a better name than GetInt.

✔️ usar um nome de tipo CLR genérico, em vez de um nome específico de idioma, nos casos raros em que um identificador não tem um significado semântico além de seu tipo.✔️ 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.

Por exemplo, um método que converte para Int64 deve ser nomeado ToInt64 , não ToLong (porque Int64 é um nome CLR para o alias específico do 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). A tabela a seguir apresenta vários tipos de dados base usando os nomes de tipo CLR (bem como os nomes de tipos correspondentes para C#, Visual Basic e 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 MinuciosaByte unsigned charunsigned char MinuciosaByte
shortshort BaixoShort 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 ºChar wchar_twchar_t ºChar
cadeia de caracteresstring Cadeia de caracteresString Cadeia de caracteresString Cadeia de caracteresString
objectobject ObjetoObject ObjetoObject ObjetoObject

✔️ usar um nome comum, como value ou item , em vez de repetir o nome do tipo, nos casos raros em que um identificador não tem significado semântico e o tipo do parâmetro não é importante.✔️ 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.

Nomeando novas versões de APIs existentesNaming New Versions of Existing APIs

✔️ usar um nome semelhante à antiga API ao criar novas versões de uma API existente.✔️ DO use a name similar to the old API when creating new versions of an existing API.

Isso ajuda a destacar a relação entre as APIs.This helps to highlight the relationship between the APIs.

✔️ preferir adicionar um sufixo em vez de um prefixo para indicar uma nova versão de uma API existente.✔️ DO prefer adding a suffix rather than a prefix to indicate a new version of an existing API.

Isso auxiliará a descoberta ao procurar a documentação ou usar o IntelliSense.This will assist discovery when browsing documentation, or using IntelliSense. A versão antiga da API será organizada perto das novas APIs, pois a maioria dos navegadores e o IntelliSense mostram identificadores em ordem alfabética.The old version of the API will be organized close to the new APIs, because most browsers and IntelliSense show identifiers in alphabetical order.

✔️ Considere usar um identificador totalmente novo, mas significativo, em vez de adicionar um sufixo ou um prefixo.✔️ CONSIDER using a brand new, but meaningful identifier, instead of adding a suffix or a prefix.

✔️ usar um sufixo numérico para indicar uma nova versão de uma API existente, especialmente se o nome existente da API for o único nome que faz sentido (ou seja, se for um padrão da indústria) e se adicionar qualquer sufixo significativo (ou alterar o nome) não for uma opção apropriada.✔️ 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.

❌Não use o sufixo "ex" (ou um semelhante) para um identificador para distingui-lo de uma versão anterior da mesma API.❌ DO NOT use the "Ex" (or a similar) suffix for an identifier to distinguish it from an earlier version of the same API.

✔️ Use o sufixo "64" ao introduzir versões de APIs que operam em um inteiro de 64 bits (um inteiro longo) em vez de um inteiro de 32 bits.✔️ 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. Você só precisa tomar essa abordagem quando existir a API de 32 bits existente; Não faça isso para APIs totalmente novas com uma versão de 64 bits.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.

Partes © 2005, 2009 Microsoft Corporation. Todos os direitos reservados.Portions © 2005, 2009 Microsoft Corporation. All rights reserved.

Reimpresso com permissão da Pearson Education, Inc. das Diretrizes de Design do Framework: convenções, linguagens e padrões para bibliotecas do .NET reutilizável, 2ª edição por Krzysztof Cwalina e Brad Abrams, publicado em 22 de outubro de 2008 por Addison-Wesley Professional como parte da série de desenvolvimento do 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.

Veja tambémSee also