Convenções gerais de nomenclatura
Nota
Este conteúdo é reimpresso com permissão da Pearson Education, Inc., a partir 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 revisto na terceira edição. Algumas das informações nesta página podem estar desatualizadas.
Esta seção descreve convenções gerais de nomenclatura relacionadas à escolha de palavras, diretrizes sobre o uso de abreviaturas e acrônimos e recomendações sobre como evitar o uso de nomes específicos do idioma.
Escolha de palavras
✔️ ESCOLHA nomes de identificadores facilmente legíveis.
Por exemplo, uma propriedade nomeada HorizontalAlignment é mais legível em inglês do que AlignmentHorizontal.
✔️ DO favorece a legibilidade em detrimento da brevidade.
O nome CanScrollHorizontally da propriedade é melhor do que ScrollableX (uma referência obscura ao eixo X).
❌ NÃO use sublinhados, hífenes ou quaisquer outros caracteres não alfanuméricos.
❌ NÃO utilize notação húngara.
❌ EVITE usar identificadores que entrem em conflito com palavras-chave de linguagens de programação amplamente utilizadas.
De acordo com a Regra 4 da 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 identificador. C#, por exemplo, usa o sinal @ como um mecanismo de escape neste 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.
Utilização de abreviaturas e acrónimos
❌ NÃO utilize abreviaturas ou contrações como parte dos nomes dos identificadores.
Por exemplo, use GetWindow em vez de GetWin.
❌ NÃO utilize siglas que não sejam amplamente aceites e, mesmo que o sejam, apenas quando necessário.
Evitando nomes específicos do idioma
✔️ USE nomes semanticamente interessantes em vez de palavras-chave específicas do idioma para nomes de tipo.
Por exemplo, GetLength é um nome melhor do que GetInt.
✔️ DO use um nome de tipo CLR genérico, em vez de um nome específico do idioma, nos raros casos em que um identificador não tem 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 longespecífico do 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 | char não assinado | Byte |
| curtas | Curtas | curtas | Int16 |
| Ushort | UInt16 | curta não assinada | UInt16 |
| Int | Inteiro | Int | Int32 |
| uint | UInt32 | int não assinado | UInt32 |
| Longo | Longo | __int64 | Int64 |
| Ulong | UInt64 | __int64 não assinado | UInt64 |
| flutuar | Solteiro | flutuar | Solteiro |
| duplo | Duplo | duplo | Duplo |
| Bool | Booleano | Bool | Booleano |
| char | Char | wchar_t | Char |
| string | Cadeia | Cadeia | Cadeia |
| objeto | Objeto | Objeto | Objeto |
✔️ USE um nome comum, como value ou item, em vez de repetir o nome do tipo, nos raros casos em que um identificador não tem significado semântico e o tipo do parâmetro não é importante.
Nomeando 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.
✔️ DO prefere adicionar um sufixo em vez de um prefixo para indicar uma nova versão de uma API existente.
Isso ajudará na descoberta ao navegar na documentação ou usar o IntelliSense. A versão antiga da API será organizada perto das novas APIs, porque a maioria dos navegadores e o IntelliSense mostram identificadores em ordem alfabética.
✔️ CONSIDERE usar 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, particularmente se o nome existente da API for o único nome que faz sentido (ou seja, se for um padrão do setor) e se adicionar qualquer sufixo significativo (ou alterar o nome) não for uma opção apropriada.
❌ NÃO use o sufixo "Ex" (ou similar) para 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 a API de 32 bits existente existir; não faça isso para APIs novas com apenas uma versão de 64 bits.
© Partes 2005, 2009 Microsoft Corporation. Todos os direitos reservados.
Reimpresso com permissão da Pearson Education, Inc., de Framework Design Guidelines: Conventions, Idioms, and Patterns for Reusable .NET Libraries, 2nd Edition por Krzysztof Cwalina e Brad Abrams, publicado em 22 de outubro de 2008 por Addison-Wesley Professional como parte da Microsoft Windows Development Series.