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

Artigo
12/20/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 Unicode Category Database.

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 ou Nl), dígitos (Nd), conexão (Pc), combinação (Mn ou Mc) e formatação (Cf). Qualquer coisa fora disso é automaticamente substituída usando _. 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 em C# usam PascalCase para nomes de tipo, namespaces e todos os membros públicos. Além disso, a equipe do dotnet/docs 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 uma Imaiúscula.
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 para os conjuntos que representem a finalidade principal do conjunto.
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 de especificação da linguagem C#. Os exemplos de sintaxe são uma exceção à regra.
- Utilize S para «structs», C para «classes».
- Utilize M para métodos.
- Use v para variáveis p para parâmetros.
- Use os parâmetros r para ref.

Dica

Você pode impor convenções de nomenclatura que dizem respeito a maiúsculas, prefixos, sufixos e separadores de palavras usando regras de nomenclatura de 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 elementos protected e protected internal, todos destinados a serem visíveis para chamadores externos.

Caso Pascal

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

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 uma interface, utilize Pascal Case e adicione um prefixo Iao nome. Este prefixo indica claramente aos consumidores que é um interface.

public interface IWorkerQueue
{
}

Ao nomear membros public de tipos, como campos, propriedades e eventos, use PascalCase. 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 notação Pascal para parâmetros, já que 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 campos private ou internal e prefixe-os com _. Use o camel case ao nomear variáveis locais, incluindo instâncias de um tipo delegado.

public class DataService
{
    private IWorkerQueue _workerQueue;
}

Dica

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

Ao trabalhar com campos static que são private ou internal, use o prefixo s_ e, para uma thread estática, use t_.

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 de tipo para tipos com um parâmetro de tipo de letra única.

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

Preceda nomes de parâmetros de tipo descritivo com "T".

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

Considere indicando 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 de TSession.

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 usando 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