Convenções comuns de código C#

2025-04-03

As convenções de codificação são essenciais para manter a legibilidade, consistência e colaboração do código dentro de uma equipe de desenvolvimento. O código que segue as práticas do setor e as diretrizes estabelecidas é mais fácil de entender, manter e ampliar. A maioria dos projetos impõe um estilo consistente por meio de convenções de código. Os projetos dotnet/docs e dotnet/samples não são exceção. Nesta série de artigos, você aprende nossas convenções de codificação e as ferramentas que usamos para aplicá-las. Você pode tomar nossas convenções como estão, ou modificá-las para atender às necessidades da sua equipe.

Escolhemos as nossas convenções com base nos seguintes objetivos:

Correção: As nossas amostras são copiadas e coladas nos seus aplicativos. Esperamos isso, então precisamos criar um código resiliente e correto, mesmo depois de várias edições.
Ensino: O objetivo de nossos exemplos é ensinar todo o .NET e C#. Por esse motivo, não colocamos restrições a nenhum recurso de idioma ou API. Em vez disso, esses exemplos ensinam quando um recurso é uma boa escolha.
Consistência: os leitores esperam uma experiência consistente em todo o nosso conteúdo. Todas as amostras devem obedecer ao mesmo estilo.
Adoção: Atualizamos agressivamente os nossos exemplos para usar novos recursos linguísticos. Essa prática aumenta a conscientização sobre novos recursos e os torna mais familiares para todos os desenvolvedores de C#.

Importante

Essas diretrizes são usadas pela Microsoft para desenvolver exemplos e documentação. Eles foram adotados a partir das diretrizes de .NET Runtime, estilo de codificação C# e do compilador C# (Roslyn). Escolhemos essas diretrizes devido à sua adoção ao longo de vários anos de desenvolvimento Open Source. Essas diretrizes ajudam os membros da comunidade a participar dos projetos de tempo de execução e compilador. Eles devem ser um exemplo de convenções comuns em C#, e não uma lista autorizada (consulte Framework Design Guidelines para obter diretrizes detalhadas).

Os objetivos de ensino e adoção são o motivo pelo qual a convenção de codificação docs difere das convenções de tempo de execução e compilador. Tanto o tempo de execução quanto o compilador têm métricas de desempenho rígidas para caminhos quentes. Muitas outras aplicações não. Nosso objetivo de ensino determina que não proíbamos nenhuma construção. Em vez disso, os exemplos mostram quando as construções devem ser usadas. Atualizamos as amostras de forma mais agressiva do que a maioria dos aplicativos de produção. Nossa meta de adoção exige que mostremos o código que você deve escrever hoje, mesmo quando o código escrito no ano passado não precisa de alterações.

Este artigo explica nossas diretrizes. As diretrizes evoluem com o tempo, e você encontrará exemplos que não seguem nossas diretrizes. Congratulamo-nos com PRs que coloquem essas amostras em conformidade ou questões que chamem a nossa atenção para amostras que devemos atualizar. As nossas diretrizes são Open Source e damos as boas-vindas a RPs e questões. No entanto, se o seu envio alterar essas recomendações, comece por abrir uma questão para discussão. Você pode usar nossas diretrizes ou adaptá-las às suas necessidades.

Ferramentas e analisadores

As ferramentas podem ajudar a sua equipa a aplicar as suas convenções. Você pode habilitar a análise de código para impor as regras de sua preferência. Você também pode criar um editorconfig para que o Visual Studio imponha automaticamente suas diretrizes de estilo. Como ponto de partida, você pode copiar o dotnet/docs.editorconfig para usar nosso estilo.

Essas ferramentas tornam mais fácil para sua equipe adotar suas diretrizes preferidas. O Visual Studio aplica as regras em todos os arquivos .editorconfig no escopo para formatar o seu código. Você pode usar várias configurações para impor convenções corporativas, convenções de equipe e até convenções de projeto granulares.

A análise de código produz avisos e diagnósticos quando deteta violações de regras. Você configura as regras que deseja aplicar ao seu projeto. Em seguida, cada compilação de CI notifica os desenvolvedores quando eles violam qualquer uma das regras.

IDs de diagnóstico

Escolha IDs de diagnóstico apropriados ao criar seus próprios analisadores

Orientações linguísticas

As secções a seguir descrevem as práticas que a equipa de documentação do .NET segue para preparar exemplos e amostras de código. Em geral, siga estas práticas:

Utilize recursos de linguagem moderna e versões em C# sempre que possível.
Evite construções de linguagem desatualizadas.
Capture apenas exceções que possam ser devidamente tratadas; evite capturar exceções genéricas. Por exemplo, o código de exemplo não deve interceptar o tipo System.Exception sem um filtro de exceção.
Use tipos de exceção específicos para fornecer mensagens de erro significativas.
Use consultas LINQ e métodos para manipulação de coleção para melhorar a legibilidade do código.
Utilize programação assíncrona com async e await para operações de entrada/saída.
Tenha cuidado com bloqueios e use Task.ConfigureAwait sempre que for apropriado.
Use as palavras-chave de idioma para tipos de dados em vez dos tipos de tempo de execução. Por exemplo, use string em vez de System.String, ou int em vez de System.Int32. Esta recomendação inclui a utilização dos tipos nint e nuint.
Use int em vez de tipos não assinados. O uso de int é comum em todo o C#, e é mais fácil interagir com outras bibliotecas quando se usa int. As exceções são para documentação específica para tipos de dados não assinados.
Use var somente quando um leitor puder inferir o tipo a partir da expressão. Os leitores visualizam as nossas amostras na plataforma de documentos. Eles não têm foco ou dicas de ferramentas que exibem o tipo de variáveis.
Escreva código com clareza e simplicidade em mente.
Evite lógicas de código excessivamente complexas e complicadas.

Seguem-se orientações mais específicas.

Dados de cadeia de caracteres

Use string interpolation para concatenar cadeias curtas, conforme mostrado no código a seguir.
```
string displayName = $"{nameList[n].LastName}, {nameList[n].FirstName}";
```

Para acrescentar cadeias de caracteres em loops, especialmente quando você estiver trabalhando com grandes quantidades de texto, use um System.Text.StringBuilder objeto.

var phrase = "lalalalalalalalalalalalalalalalalalalalalalalalalalalalalala";
var manyPhrases = new StringBuilder();
for (var i = 0; i < 10000; i++)
{
    manyPhrases.Append(phrase);
}
//Console.WriteLine("tra" + manyPhrases);

Prefira literais de strings sem processamento em vez de sequências de escape ou strings verbatim.

var message = """
    This is a long message that spans across multiple lines.
    It uses raw string literals. This means we can 
    also include characters like \n and \t without escaping them.
    """;

Use a interpolação de cadeia de caracteres baseada em expressão em vez da interpolação de cadeia de caracteres posicional.

// Execute the queries.
Console.WriteLine("scoreQuery:");
foreach (var student in scoreQuery)
{
    Console.WriteLine($"{student.Last} Score: {student.score}");
}

Construtores e inicialização

Use o caso Pascal para parâmetros primários do construtor em tipos de registro:
```
public record Person(string FirstName, string LastName);
```
Utilize camel case para parâmetros primários do construtor em tipos de classe e estrutura.

Utilize as propriedades required em vez de construtores para forçar a inicialização de valores de propriedade.

public class LabelledContainer<T>(string label)
{
    public string Label { get; } = label;
    public required T Contents 
    { 
        get;
        init;
    }
}

Matrizes e coleções

Use expressões de coleção para inicializar todos os tipos de coleção:

string[] vowels = [ "a", "e", "i", "o", "u" ];

Delegados

Use Func<> e Action<> em vez de definir tipos de delegados. Em uma classe, defina o método delegado.

Action<string> actionExample1 = x => Console.WriteLine($"x is: {x}");

Action<string, string> actionExample2 = (x, y) =>
    Console.WriteLine($"x is: {x}, y is {y}");

Func<string, int> funcExample1 = x => Convert.ToInt32(x);

Func<int, int, int> funcExample2 = (x, y) => x + y;

Chame o método usando a assinatura definida pelo Func<> ou Action<> delegate.

actionExample1("string for x");

actionExample2("string for x", "string for y");

Console.WriteLine($"The value is {funcExample1("1")}");

Console.WriteLine($"The sum is {funcExample2(1, 2)}");

Se você criar instâncias de um tipo delegado, use a sintaxe concisa. Em uma classe, defina o tipo de delegado e um método que tenha uma assinatura correspondente.
```
public delegate void Del(string message);

public static void DelMethod(string str)
{
    Console.WriteLine($"DelMethod argument: {str}");
}
```
Crie uma instância do tipo de delegado e chame-a. A declaração a seguir mostra a sintaxe condensada.
```
Del exampleDel2 = DelMethod;
exampleDel2("Hey");
```

A declaração a seguir usa a sintaxe completa.

Del exampleDel1 = new Del(DelMethod);
exampleDel1("Hey");

`try-catch` e `using` declarações no tratamento de exceções

Utilize uma instrução try-catch para a maior parte do tratamento de exceções.

static double ComputeDistance(double x1, double y1, double x2, double y2)
{
    try
    {
        return Math.Sqrt((x1 - x2) * (x1 - x2) + (y1 - y2) * (y1 - y2));
    }
    catch (System.ArithmeticException ex)
    {
        Console.WriteLine($"Arithmetic overflow or underflow: {ex}");
        throw;
    }
}

Simplifique o seu código usando a instrução using do C#. Se tiveres uma declaração try-finally na qual o único código no bloco é uma chamada ao método finally, usa uma Dispose declaração em vez disso.

No exemplo a seguir, a instrução try-finally só chama Dispose no bloco finally.
```
Font bodyStyle = new Font("Arial", 10.0f);
try
{
    byte charset = bodyStyle.GdiCharSet;
}
finally
{
    bodyStyle?.Dispose();
}
```
Você pode fazer a mesma coisa com uma using declaração.
```
using (Font arial = new Font("Arial", 10.0f))
{
    byte charset2 = arial.GdiCharSet;
}
```
Use a nova sintaxe using que não requer parênteses:
```
using Font normalStyle = new Font("Arial", 10.0f);
byte charset3 = normalStyle.GdiCharSet;
```

`&&` e `||` operadores

Use && em vez de & e || em vez de | quando você executa comparações, como mostrado no exemplo a seguir.

Console.Write("Enter a dividend: ");
int dividend = Convert.ToInt32(Console.ReadLine());

Console.Write("Enter a divisor: ");
int divisor = Convert.ToInt32(Console.ReadLine());

if ((divisor != 0) && (dividend / divisor) is var result)
{
    Console.WriteLine($"Quotient: {result}");
}
else
{
    Console.WriteLine("Attempted division by 0 ends up here.");
}

Se o divisor for 0, a segunda cláusula na if instrução causaria um erro em tempo de execução. Mas o operador && entra em curto-circuito quando a primeira expressão é falsa. Ou seja, não avalia a segunda expressão. O operador & avaliaria ambos, resultando em um erro em tempo de execução quando divisor é 0.

`new` Operador

Use uma das formas concisas de instanciação de objeto quando o tipo de variável corresponder ao tipo de objeto, conforme mostrado nas declarações a seguir. Este formulário não é válido quando a variável é um tipo de interface ou uma classe base do tipo de tempo de execução.
```
var firstExample = new ExampleClass();
```
```
ExampleClass instance2 = new();
```
As declarações anteriores equivalem à declaração seguinte.
```
ExampleClass secondExample = new ExampleClass();
```

Use inicializadores de objeto para simplificar a criação de objetos, conforme mostrado no exemplo a seguir.

var thirdExample = new ExampleClass { Name = "Desktop", ID = 37414,
    Location = "Redmond", Age = 2.3 };

O exemplo a seguir define as mesmas propriedades do exemplo anterior, mas não usa inicializadores.

var fourthExample = new ExampleClass();
fourthExample.Name = "Desktop";
fourthExample.ID = 37414;
fourthExample.Location = "Redmond";
fourthExample.Age = 2.3;

Manipulação de eventos

Use uma expressão lambda para definir um manipulador de eventos que você não precisa remover posteriormente:

public Form2()
{
    this.Click += (s, e) =>
        {
            MessageBox.Show(
                ((MouseEventArgs)e).Location.ToString());
        };
}

A expressão lambda encurta a seguinte definição tradicional.

public Form1()
{
    this.Click += new EventHandler(Form1_Click);
}

void Form1_Click(object? sender, EventArgs e)
{
    MessageBox.Show(((MouseEventArgs)e).Location.ToString());
}

Membros estáticos

Chame membros estáticos usando o nome da classe: ClassName.StaticMember. Essa prática torna o código mais legível, tornando o acesso estático claro. Não qualifique um membro estático definido em uma classe base com o nome de uma classe derivada. Enquanto esse código é compilado, a legibilidade do código é enganosa, e o código pode quebrar no futuro se você adicionar um membro estático com o mesmo nome à classe derivada.

Consultas LINQ

Use nomes significativos para variáveis de consulta. O exemplo a seguir usa seattleCustomers para clientes que estão localizados em Seattle.

var seattleCustomers = from customer in Customers
                       where customer.City == "Seattle"
                       select customer.Name;

Use aliases para certificar-se de que os nomes de propriedade de tipos anónimos estão corretamente capitalizados, usando a notação Pascal.

var localDistributors =
    from customer in Customers
    join distributor in Distributors on customer.City equals distributor.City
    select new { Customer = customer, Distributor = distributor };

Renomeie propriedades quando os nomes de propriedade no resultado forem ambíguos. Por exemplo, se sua consulta retornar um nome de cliente e um nome de distribuidor, em vez de deixá-los como uma forma de Name no resultado, renomeie-os para esclarecer CustomerName é o nome de um cliente e DistributorName é o nome de um distribuidor.
```
var localDistributors2 =
    from customer in Customers
    join distributor in Distributors on customer.City equals distributor.City
    select new { CustomerName = customer.Name, DistributorName = distributor.Name };
```
Use a digitação implícita na declaração de variáveis de consulta e variáveis de intervalo. Esta orientação sobre digitação implícita em consultas LINQ substitui as regras gerais para variáveis locais digitadas implicitamente. As consultas LINQ geralmente usam projeções que criam tipos anônimos. Outras expressões de consulta criam resultados com tipos genéricos aninhados. As variáveis digitadas implícitas são geralmente mais legíveis.
```
var seattleCustomers = from customer in Customers
                       where customer.City == "Seattle"
                       select customer.Name;
```
Alinhe as cláusulas de consulta sob a from cláusula, conforme mostrado nos exemplos anteriores.

Utilize cláusulas where antes de outras de consulta para garantir que as cláusulas posteriores operem no conjunto reduzido e filtrado de dados.

var seattleCustomers2 = from customer in Customers
                        where customer.City == "Seattle"
                        orderby customer.Name
                        select customer;

Acesse coleções internas com várias cláusulas from em vez de uma cláusula join. Por exemplo, uma coleção de Student objetos pode conter uma coleção de pontuações de teste. Quando a consulta a seguir é executada, ela retorna cada pontuação acima de 90, juntamente com o nome da família do aluno que recebeu a pontuação.
```
var scoreQuery = from student in students
                 from score in student.Scores
                 where score > 90
                 select new { Last = student.LastName, score };
```

Variáveis locais escritas implicitamente

Use tipagem implícita para variáveis locais quando o tipo da variável for óbvio do lado direito da atribuição.
```
var message = "This is clearly a string.";
var currentTemperature = 27;
```
Não use var quando não for possível determinar o tipo a partir do lado direito da atribuição. Não assuma que o tipo é claro pelo nome do método. Um tipo de variável é considerado claro se for um operador new, uma conversão explícita ou atribuição a um valor literal.
```
int numberOfIterations = Convert.ToInt32(Console.ReadLine());
int currentMaximum = ExampleClass.ResultSoFar();
```
Não use nomes de variáveis para especificar o tipo da variável. Pode não estar correto. Em vez disso, use o tipo para especificar o tipo e use o nome da variável para indicar as informações semânticas da variável. O exemplo a seguir deve usar string para o tipo e algo como iterations para indicar o significado das informações lidas do console.
```
var inputInt = Console.ReadLine();
Console.WriteLine(inputInt);
```
Evite o uso de var no lugar de dinâmico. Use dynamic quando quiser inferência de tipo em tempo de execução. Para obter mais informações, consulte Usando o tipo dinâmico (Guia de Programação em C#).

Utilize uma tipagem implícita para a variável de ciclo em for ciclos.

O exemplo seguinte utiliza tipagem implícita numa instrução for.

var phrase = "lalalalalalalalalalalalalalalalalalalalalalalalalalalalalala";
var manyPhrases = new StringBuilder();
for (var i = 0; i < 10000; i++)
{
    manyPhrases.Append(phrase);
}
//Console.WriteLine("tra" + manyPhrases);

Não use digitação implícita para determinar o tipo da variável de loop em foreach loops. Na maioria dos casos, o tipo de elementos na coleção não é imediatamente óbvio. O nome da coleção não deve ser usado apenas para inferir o tipo de seus elementos.

O exemplo a seguir usa a tipagem explícita numa foreach instrução.
```
foreach (char ch in laugh)
{
    if (ch == 'h')
    {
        Console.Write("H");
    }
    else
    {
        Console.Write(ch);
    }
}
Console.WriteLine();
```
use o tipo implícito para as sequências de resultados em consultas LINQ. A seção sobre LINQ explica que muitas consultas LINQ resultam em tipos anônimos onde tipos implícitos devem ser usados. Outras consultas resultam em tipos genéricos aninhados onde var é mais legível.

Nota

Tenha cuidado para não alterar acidentalmente um tipo de elemento da coleção iterável. Por exemplo, é fácil alternar de System.Linq.IQueryable para System.Collections.IEnumerable em uma instrução foreach, o que altera a execução de uma consulta.

Algumas das nossas amostras explicam o tipo natural de uma expressão. Essas amostras devem usar var para que o compilador escolha o tipo natural. Embora esses exemplos sejam menos óbvios, o uso de var é necessário para a amostra. O texto deve explicar o comportamento.

Declarações de namespace de âmbito de ficheiro

A maioria dos arquivos de código declara um único namespace. Portanto, os nossos exemplos devem usar as declarações de namespace com escopo de ficheiro:

namespace MySampleCode;

Coloque as diretivas "using" fora da declaração de "namespace"

Quando uma using diretiva está fora de uma declaração de namespace, esse namespace importado é seu nome totalmente qualificado. O nome totalmente qualificado é mais claro. Quando a using diretiva está dentro do namespace, ela pode ser relativa a esse namespace ou seu nome totalmente qualificado.

using Azure;

namespace CoolStuff.AwesomeFeature
{
    public class Awesome
    {
        public void Stuff()
        {
            WaitUntil wait = WaitUntil.Completed;
            // ...
        }
    }
}

Supondo que haja uma referência (direta ou indireta) à WaitUntil classe.

Agora, vamos mudá-lo um pouco:

namespace CoolStuff.AwesomeFeature
{
    using Azure;

    public class Awesome
    {
        public void Stuff()
        {
            WaitUntil wait = WaitUntil.Completed;
            // ...
        }
    }
}

E compila hoje. E amanhã. Mas então, em algum momento da próxima semana, o código anterior (intocado) falha com dois erros:

- error CS0246: The type or namespace name 'WaitUntil' could not be found (are you missing a using directive or an assembly reference?)
- error CS0103: The name 'WaitUntil' does not exist in the current context

Uma das dependências que esta classe introduz num namespace termina com .Azure:

namespace CoolStuff.Azure
{
    public class SecretsManagement
    {
        public string FetchFromKeyVault(string vaultId, string secretId) { return null; }
    }
}

Uma using diretiva colocada dentro de um namespace é sensível ao contexto e complica a resolução de nomes. Neste exemplo, é o primeiro namespace encontrado.

CoolStuff.AwesomeFeature.Azure
CoolStuff.Azure
Azure

Adicionar um novo namespace que corresponda a CoolStuff.Azure ou CoolStuff.AwesomeFeature.Azure corresponderia antes do namespace global Azure. Você pode resolvê-lo adicionando o global:: modificador à using declaração. No entanto, é mais fácil colocar as declarações using fora do namespace.

namespace CoolStuff.AwesomeFeature
{
    using global::Azure;

    public class Awesome
    {
        public void Stuff()
        {
            WaitUntil wait = WaitUntil.Completed;
            // ...
        }
    }
}

Diretrizes de estilo

Em geral, use o seguinte formato para exemplos de código:

Use quatro espaços para indentar. Não utilize tabulações.
Alinhe o código consistentemente para melhorar a legibilidade.
Limite as linhas a 65 caracteres para melhorar a legibilidade do código em documentos, especialmente em telas de dispositivos móveis.
Melhore a clareza e a experiência do usuário dividindo instruções longas em várias linhas.
Use o estilo "Allman" para chaves: a chave de abertura e a chave de fecho devem estar cada uma em sua própria linha nova. As chaves alinham-se com o nível de recuo atual.
As quebras de linha devem ocorrer antes dos operadores binários, se necessário.

Estilo do comentário

Use comentários de linha única (//) para breves explicações.
Evite comentários com várias linhas (/* */) para explicações mais longas.
Os comentários nos exemplos de código não estão traduzidos. Isso significa que as explicações incorporadas no código não são traduzidas. Texto explicativo mais longo deve ser colocado no artigo complementar, para que possa ser localizado.
Para descrever métodos, classes, campos e todos os membros públicos usam comentários XML.
Coloque o comentário em uma linha separada, não no final de uma linha de código.
Comece o texto do comentário com uma letra maiúscula.
Termine o texto do comentário com um ponto.
Insira um espaço entre o delimitador de comentários (//) e o texto do comentário, conforme mostrado no exemplo a seguir.
```
// The following declaration creates a query. It does not run
// the query.
```

Convenções de layout

Um bom layout usa a formatação para enfatizar a estrutura do seu código e para tornar o código mais fácil de ler. Os exemplos e amostras da Microsoft estão em conformidade com as seguintes convenções.

Use as configurações padrão do Editor de Códigos (recuo inteligente, recuos de quatro caracteres, guias salvas como espaços). Para obter mais informações, consulte Opções, Editor de texto, C#, Formatação.
Escreva apenas uma instrução por linha.
Escreva apenas uma declaração por linha.
Se as linhas de continuação não forem indentadas automaticamente, indente-as uma parada de tabulação (quatro espaços).
Adicione pelo menos uma linha em branco entre definições de método e definições de propriedade.
Use parênteses para tornar as cláusulas em uma expressão aparente, conforme mostrado no código a seguir.
```
if ((startX > endX) && (startX > previousX))
{
    // Take appropriate action.
}
```

As exceções são quando o exemplo explica a precedência do operador ou da expressão.

Segurança

Siga as diretrizes em Diretrizes de codificação segura.