Regras e convenções de nomenclatura do identificador C#

Artigo
03/15/2024

Um identificador é o nome que você atribui a um tipo (classe, interface, struct, delegado ou enum), membro, variável ou namespace.

Regras de nomenclatura

Os identificadores válidos devem seguir estas regras. O compilador C# produz um erro para qualquer identificador que não siga estas regras:

Os identificadores devem começar com uma letra ou sublinhado (_).
Os identificadores podem conter caracteres de letra Unicode, caracteres de dígitos decimais, caracteres de conexão Unicode, caracteres de combinação Unicode ou caracteres de formatação Unicode. Para obter mais informações sobre categorias Unicode, consulte o Banco de dados de categorias Unicode.

Você pode declarar identificadores que correspondem a palavras-chave C# usando o prefixo @ no identificador. O @ não faz parte do nome do identificador. Por exemplo, @if declara um identificador chamado if. Estes identificadores literais destinam-se principalmente à interoperabilidade com identificadores declarados noutras línguas.

Para obter uma definição completa de identificadores válidos, consulte o artigo Identificadores na Especificação da linguagem C#.

Importante

A especificação da linguagem C# só permite letras (Lu, Ll, Lt, Lm, Lo ou Nl), dígitos (Nd), conexão (Pc), combinação (Mn ou Mc) e formatação (Cf) categorias. Qualquer coisa fora disso é automaticamente substituída usando _o . Isso pode afetar determinados caracteres Unicode.

Convenções de nomenclatura

Além das regras, convenções para nomes de identificador são usadas em todas as APIs .NET. Essas convenções fornecem consistência para nomes, mas o compilador não as impõe. Você é livre para usar diferentes convenções em seus projetos.

Por convenção, os programas C# usam PascalCase para nomes de tipo, namespaces e todos os membros públicos. Além disso, a dotnet/docs equipe usa as seguintes convenções, adotadas a partir do estilo de codificação da equipe do .NET Runtime:

Os nomes das interfaces começam com maiúsculas I.
Os tipos de atributos terminam com a palavra Attribute.
Os tipos Enum usam um substantivo singular para não-bandeiras, e um substantivo plural para bandeiras.
Os identificadores não devem conter dois caracteres de sublinhado (_) consecutivos. Esses nomes são reservados para identificadores gerados pelo compilador.
Use nomes significativos e descritivos para variáveis, métodos e classes.
Prefira a clareza à brevidade.
Use PascalCase para nomes de classe e nomes de método.
Use camelCase para parâmetros de método e variáveis locais.
Use PascalCase para nomes constantes, campos e constantes locais.
Os campos de instância privada começam com um sublinhado (_) e o texto restante é camelCased.
Os campos estáticos começam com s_. Essa convenção não é o comportamento padrão do Visual Studio, nem faz parte das diretrizes de design do Framework, mas é configurável em editorconfig.
Evite usar abreviaturas ou acrónimos nos nomes, exceto abreviaturas amplamente conhecidas e aceites.
Use namespaces significativos e descritivos que seguem a notação de nome de domínio inversa.
Escolha nomes de assembly que representem a finalidade principal do assembly.
Evite usar nomes de letra única, exceto para contadores de loop simples. Além disso, exemplos de sintaxe que descrevem a sintaxe de construções C# geralmente usam os seguintes nomes de letra única que correspondem à convenção usada na especificação da linguagem C#. Os exemplos de sintaxe são uma exceção à regra.
- Use S para structs, C para classes.
- Use M para métodos.
- Use v para variáveis, p para parâmetros.
- Use r para ref parâmetros.

Gorjeta

Você pode impor convenções de nomenclatura que dizem respeito a maiúsculas, prefixos, sufixos e separadores de palavras usando regras de nomenclatura no estilo de código.

Nos exemplos a seguir, as orientações referentes aos elementos marcados public também são aplicáveis ao trabalhar com protected elementos e protected internal , todos destinados a serem visíveis para chamadores externos.

Caso Pascal

Use o invólucro pascal ("PascalCasing") ao nomear um class, interface, struct, ou delegate tipo.

public class DataService
{
}

public record PhysicalAddress(
    string Street,
    string City,
    string StateOrProvince,
    string ZipCode);

public struct ValueCoordinate
{
}

public delegate void DelegateType(string message);

Ao nomear um interface, use a caixa pascal além de prefixar o nome com um Iarquivo . Este prefixo indica claramente aos consumidores que é um interface.

public interface IWorkerQueue
{
}

Ao nomear public membros de tipos, como campos, propriedades, eventos, use a caixa pascal. Além disso, use o invólucro pascal para todos os métodos e funções locais.

public class ExampleEvents
{
    // A public field, these should be used sparingly
    public bool IsValid;

    // An init-only property
    public IWorkerQueue WorkerQueue { get; init; }

    // An event
    public event Action EventProcessing;

    // Method
    public void StartEventProcessing()
    {
        // Local function
        static int CountQueueItems() => WorkerQueue.Count;
        // ...
    }
}

Ao escrever registros posicionais, use a caixa pascal para parâmetros, pois eles são as propriedades públicas do registro.

public record PhysicalAddress(
    string Street,
    string City,
    string StateOrProvince,
    string ZipCode);

Para obter mais informações sobre registros posicionais, consulte Sintaxe posicional para definição de propriedade.

Caixa de camelo

Use o invólucro de camelo ("camelCasing") ao nomear private ou internal campos e prefixe-os com _. Use a caixa de camelo ao nomear variáveis locais, incluindo instâncias de um tipo delegado.

public class DataService
{
    private IWorkerQueue _workerQueue;
}

Gorjeta

Ao editar o código C# que segue essas convenções de nomenclatura em um IDE que oferece suporte à conclusão de instrução, a digitação _ mostrará todos os membros com escopo de objeto.

Ao trabalhar com static campos que são private ou internal, use o prefixo s_ e para uso t_estático de thread .

public class DataService
{
    private static IWorkerQueue s_workerQueue;

    [ThreadStatic]
    private static TimeSpan t_timeSpan;
}

Ao escrever parâmetros de método, use caixa de camelo.

public T SomeMethod<T>(int someNumber, bool isValid)
{
}

Para obter mais informações sobre convenções de nomenclatura em C#, consulte o estilo de codificação da equipe do .NET Runtime.

Diretrizes de nomenclatura de parâmetros de tipo

As diretrizes a seguir se aplicam a parâmetros de tipo em parâmetros de tipo genéricos. Os parâmetros de tipo são os espaços reservados para argumentos em um tipo genérico ou um método genérico. Você pode ler mais sobre parâmetros de tipo genéricos no guia de programação em C#.

Nomeie parâmetros de tipo genéricos com nomes descritivos, a menos que um nome de letra única seja completamente autoexplicativo e um nome descritivo não agregaria valor.
```
public interface ISessionChannel<TSession> { /*...*/ }
public delegate TOutput Converter<TInput, TOutput>(TInput from);
public class List<T> { /*...*/ }
```

Considere usar T como o nome do parâmetro type para tipos com um único parâmetro de tipo de letra.

public int IComparer<T>() { return 0; }
public delegate bool Predicate<T>(T item);
public struct Nullable<T> where T : struct { /*...*/ }

Faça nomes de parâmetros de tipo descritivo de prefixo com "T".

public interface ISessionChannel<TSession>
{
    TSession Session { get; }
}

Considere indicar restrições colocadas em um parâmetro de tipo no nome do parâmetro. Por exemplo, um parâmetro restrito a ISession pode ser chamado TSessionde .

A regra de análise de código CA1715 pode ser usada para garantir que os parâmetros de tipo sejam nomeados adequadamente.

Convenções de nomenclatura extras

Exemplos que não incluem o uso de diretivas, usam qualificações de namespace. Se você souber que um namespace é importado por padrão em um projeto, não precisará qualificar totalmente os nomes desse namespace. Os nomes qualificados podem ser quebrados após um ponto (.) se forem muito longos para uma única linha, conforme mostrado no exemplo a seguir.
```
var currentPerformanceCounterCategory = new System.Diagnostics.
    PerformanceCounterCategory();
```
Não é necessário alterar os nomes dos objetos que foram criados usando as ferramentas de designer do Visual Studio para torná-los adequados a outras diretrizes.

Partilhar via