Convenções de nomenclatura gerais
Observação
Este conteúdo é reimpresso com permissão da Pearson Education, Inc. de Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition. Essa edição foi publicada em 2008 e, desde então, o livro foi totalmente revisado na terceira edição. Algumas das informações nesta página podem estar desatualizadas.
Esta seção descreve convenções de nomenclatura gerais relacionadas à escolha de palavras, diretrizes sobre o uso de abreviações e acrônimos e recomendações sobre como evitar o uso de nomes específicos da linguagem.
Escolha das palavras
✔️ ESCOLHA nomes de identificador facilmente legíveis.
Por exemplo, uma propriedade nomeada HorizontalAlignment é mais legível em inglês do que AlignmentHorizontal.
✔️ FAVOREÇA a legibilidade em vez da brevidade.
O nome de propriedade CanScrollHorizontally é melhor do que ScrollableX (uma referência obscura ao eixo X).
❌ NÃO use sublinhados, hifens ou outros caracteres não alfanuméricos.
❌ NÃO use notação húngara.
❌ EVITE o uso de identificadores que entram em conflito com palavras-chave de linguagens de programação amplamente usadas.
De acordo com a Regra 4 da CLS (Common Language Specification), todas as linguagens compatíveis devem fornecer um mecanismo que permita o acesso a itens nomeados que usam uma palavra-chave dessa linguagem como identificador. O C#, por exemplo, usa o sinal @ como um mecanismo de escape nesse caso. No entanto, ainda é uma boa ideia evitar palavras-chave comuns, porque é muito mais difícil usar um método com a sequência de escape do que um sem ela.
Usar abreviações e acrônimos
❌ NÃO use abreviações ou contrações como parte de nomes de identificador.
Por exemplo, use GetWindow em vez de GetWin.
❌ NÃO use acrônimos que não sejam amplamente aceitos e, mesmo que o sejam, somente quando necessário.
Evitar nomes específicos de linguagem
✔️ USE nomes semanticamente interessantes em vez de palavras-chave específicas da linguagem para nomes de tipo.
Por exemplo, GetLength é um nome melhor do que GetInt.
✔️ USE um nome de tipo CLR genérico, em vez de um nome específico da linguagem, nos casos raros em que um identificador não tem nenhum significado semântico além de seu tipo.
Por exemplo, um método de conversão para Int64 deve ser nomeado ToInt64, não ToLong (porque Int64 é um nome CLR para o alias long específico de C#). A tabela a seguir apresenta vários tipos de dados base usando os nomes de tipo CLR (bem como os nomes de tipo correspondentes para C#, Visual Basic e 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 | Inteiro | int | Int32 |
| uint | UInt32 | unsigned int | UInt32 |
| longo | Long | __int64 | Int64 |
| ulong | UInt64 | unsigned __int64 | UInt64 |
| float | Single | float | Single |
| double | Double | double | Double |
| bool | Booliano | bool | Booliano |
| char | Char | wchar_t | Char |
| cadeia de caracteres | Cadeia de caracteres | Cadeia de caracteres | Cadeia de caracteres |
| object | Objeto | Objeto | Objeto |
✔️ USE um nome comum, como value ou item, em vez de repetir o nome do tipo, nos casos raros em que um identificador não tiver significado semântico e o tipo do parâmetro não for importante.
Nomear novas versões de APIs existentes
✔️ USE um nome semelhante à API antiga ao criar novas versões de uma API existente.
Isso ajuda a destacar a relação entre as APIs.
✔️ PREFIRA adicionar um sufixo em vez de um prefixo para indicar uma nova versão de uma API existente.
Isso ajudará a descoberta ao navegar na documentação ou a usar o 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.
✔️ CONSIDERE o uso de um identificador novo, mas significativo, em vez de adicionar um sufixo ou um prefixo.
✔️ USE 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 faça sentido (ou seja, se for um padrão do setor) e se adicionar um sufixo significativo (ou alterar o nome) não for uma opção apropriada.
❌ NÃO use o sufixo "Ex" (ou similar) em um identificador para distingui-lo de uma versão anterior da mesma 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. Você só precisa adotar essa abordagem quando houver a API de 32 bits; não faça isso com APIs novas com apenas a versão de 64 bits.
Portions © 2005, 2009 Microsoft Corporation. Todos os direitos reservados.
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.