Convenções de codificação em C# (Guia de Programação em C#)C# Coding Conventions (C# Programming Guide)

As convenções de codificação atendem às seguintes finalidades:Coding conventions serve the following purposes:

  • Criam uma aparência consistente para o código, para que os leitores possam se concentrar no conteúdo e não no layout.They create a consistent look to the code, so that readers can focus on content, not layout.

  • Permitem que os leitores entendam o código com mais rapidez, fazendo suposições com base na experiência anterior.They enable readers to understand the code more quickly by making assumptions based on previous experience.

  • Facilitam a cópia, a alteração e a manutenção do código.They facilitate copying, changing, and maintaining the code.

  • Demonstram as práticas recomendadas do C#.They demonstrate C# best practices.

As diretrizes neste tópico são usadas pela Microsoft para desenvolver amostras e documentação.The guidelines in this topic are used by Microsoft to develop samples and documentation.

Convenções de nomenclaturaNaming Conventions

  • Em exemplos curtos que não incluem diretivas using, use as qualificações do namespace.In short examples that do not include using directives, use namespace qualifications. Se você souber que um namespace é importado por padrão em um projeto, não precisará qualificar totalmente os nomes desse namespace.If you know that a namespace is imported by default in a project, you do not have to fully qualify the names from that namespace. Nomes qualificados podem ser interrompidos após um ponto (.) se forem muito longos para uma única linha, conforme mostrado no exemplo a seguir.Qualified names can be broken after a dot (.) if they are too long for a single line, as shown in the following example.

    var currentPerformanceCounterCategory = new System.Diagnostics.
        PerformanceCounterCategory();
    
  • Não é necessário alterar os nomes de objetos que foram criados usando as ferramentas de designer do Visual Studio para adequá-los a outras diretrizes.You do not have to change the names of objects that were created by using the Visual Studio designer tools to make them fit other guidelines.

Convenções de LayoutLayout Conventions

Um bom layout usa formatação para enfatizar a estrutura do código e para facilitar a leitura de código.Good layout uses formatting to emphasize the structure of your code and to make the code easier to read. Exemplos e amostras Microsoft estão em conformidade com as seguintes convenções:Microsoft examples and samples conform to the following conventions:

  • Use as configurações padrão do Editor de códigos (recuo inteligente, recuos de quatro caracteres, guias salvas como espaços).Use the default Code Editor settings (smart indenting, four-character indents, tabs saved as spaces). Para obter mais informações, consulte Opções, Editor de Texto, C#, Formatação.For more information, see Options, Text Editor, C#, Formatting.

  • Gravar apenas uma instrução por linha.Write only one statement per line.

  • Gravar apenas uma declaração por linha.Write only one declaration per line.

  • Se as linhas de continuação não devem recuar automaticamente, recue-as uma tabulação (quatro espaços).If continuation lines are not indented automatically, indent them one tab stop (four spaces).

  • Adicione pelo menos uma linha em branco entre as definições de método e de propriedade.Add at least one blank line between method definitions and property definitions.

  • Use parênteses para criar cláusulas em uma expressão aparente, conforme mostrado no código a seguir.Use parentheses to make clauses in an expression apparent, as shown in the following code.

    if ((val1 > val2) && (val1 > val3))
    {
        // Take appropriate action.
    }
    

Comentando ConvençõesCommenting Conventions

  • Coloque o comentário em uma linha separada, não no final de uma linha de código.Place the comment on a separate line, not at the end of a line of code.

  • Comece o texto do comentário com uma letra maiúscula.Begin comment text with an uppercase letter.

  • Termine o texto do comentário com um ponto final.End comment text with a period.

  • Insira um espaço entre o delimitador de comentário (/ /) e o texto do comentário, conforme mostrado no exemplo a seguir.Insert one space between the comment delimiter (//) and the comment text, as shown in the following example.

    // The following declaration creates a query. It does not run
    // the query.
    
  • Não crie blocos de asteriscos formatados em torno dos comentários.Do not create formatted blocks of asterisks around comments.

Diretrizes de LinguagemLanguage Guidelines

As seções a seguir descrevem práticas que a equipe de C# segue para preparar exemplos e amostras do código.The following sections describe practices that the C# team follows to prepare code examples and samples.

Tipo de dados da cadeia de caracteresString Data Type

  • Use a interpolação de cadeia de caracteres para concatenar cadeias de caracteres curtas, como é mostrado no código a seguir.Use string interpolation to concatenate short strings, as shown in the following code.

    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 objeto StringBuilder.To append strings in loops, especially when you are working with large amounts of text, use a StringBuilder object.

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

Variáveis Locais Tipadas ImplicitamenteImplicitly Typed Local Variables

  • Use a digitação implícita para variáveis locais quando o tipo da variável for óbvio do lado direito da atribuição ou quando o tipo exato não for importante.Use implicit typing for local variables when the type of the variable is obvious from the right side of the assignment, or when the precise type is not important.

    // When the type of a variable is clear from the context, use var 
    // in the declaration.
    var var1 = "This is clearly a string.";
    var var2 = 27;
    var var3 = Convert.ToInt32(Console.ReadLine());
    
  • Não use var quando o tipo não estiver aparente no lado direito da atribuição.Do not use var when the type is not apparent from the right side of the assignment.

    // When the type of a variable is not clear from the context, use an
    // explicit type.
    int var4 = ExampleClass.ResultSoFar();
    
  • Não se baseie no nome da variável para especificar o tipo dela.Do not rely on the variable name to specify the type of the variable. Ele pode não estar correto.It might not be correct.

    // Naming the following variable inputInt is misleading. 
    // It is a string.
    var inputInt = Console.ReadLine();
    Console.WriteLine(inputInt);
    
  • Evite o uso de var em vez de dynamic.Avoid the use of var in place of dynamic.

  • Use a digitação implícita para determinar o tipo da variável de loop nos loops for e foreach.Use implicit typing to determine the type of the loop variable in for and foreach loops.

    O exemplo a seguir usa digitação implícita em uma instrução for.The following example uses implicit typing in a for statement.

    var syllable = "ha";
    var laugh = "";
    for (var i = 0; i < 10; i++)
    {
        laugh += syllable;
        Console.WriteLine(laugh);
    }
    

    O exemplo a seguir usa digitação implícita em uma instrução foreach.The following example uses implicit typing in a foreach statement.

    foreach (var ch in laugh)
    {
        if (ch == 'h')
            Console.Write("H");
        else
            Console.Write(ch);
    }
    Console.WriteLine();
    

Tipo de Dados Sem SinalUnsigned Data Type

  • Em geral, use int em vez de tipos sem assinatura.In general, use int rather than unsigned types. O uso de int é comum em todo o C#, e é mais fácil interagir com outras bibliotecas ao usar int.The use of int is common throughout C#, and it is easier to interact with other libraries when you use int.

MatrizesArrays

  • Use a sintaxe concisa ao inicializar matrizes na linha da declaração.Use the concise syntax when you initialize arrays on the declaration line.

    // Preferred syntax. Note that you cannot use var here instead of string[].
    string[] vowels1 = { "a", "e", "i", "o", "u" };
    
    
    // If you use explicit instantiation, you can use var.
    var vowels2 = new string[] { "a", "e", "i", "o", "u" };
    
    // If you specify an array size, you must initialize the elements one at a time.
    var vowels3 = new string[5];
    vowels3[0] = "a";
    vowels3[1] = "e";
    // And so on.
    

DelegadosDelegates

  • Use a sintaxe concisa ao criar instâncias de um tipo delegado.Use the concise syntax to create instances of a delegate type.

    // First, in class Program, define the delegate type and a method that  
    // has a matching signature.
    
    // Define the type.
    public delegate void Del(string message);
    
    // Define a method that has a matching signature.
    public static void DelMethod(string str)
    {
        Console.WriteLine("DelMethod argument: {0}", str);
    }
    
    // In the Main method, create an instance of Del.
    
    // Preferred: Create an instance of Del by using condensed syntax.
    Del exampleDel2 = DelMethod;
    
    // The following declaration uses the full syntax.
    Del exampleDel1 = new Del(DelMethod);
    

try-catch e instruções de uso no tratamento de exceçãotry-catch and using Statements in Exception Handling

  • Use uma instrução try-catch para a maioria da manipulação de exceções.Use a try-catch statement for most exception handling.

    static string GetValueFromArray(string[] array, int index)
    {
        try
        {
            return array[index];
        }
        catch (System.IndexOutOfRangeException ex)
        {
            Console.WriteLine("Index is out of range: {0}", index);
            throw;
        }
    }
    
  • Simplifique o código usando a instrução using do #C.Simplify your code by using the C# using statement. Se você tiver uma instrução try-finally na qual o único código do bloco finally é uma chamada para o método Dispose, use, em vez disso, uma instrução using.If you have a try-finally statement in which the only code in the finally block is a call to the Dispose method, use a using statement instead.

    // This try-finally statement only calls Dispose in the finally block.
    Font font1 = new Font("Arial", 10.0f);
    try
    {
        byte charset = font1.GdiCharSet;
    }
    finally
    {
        if (font1 != null)
        {
            ((IDisposable)font1).Dispose();
        }
    }
    
    
    // You can do the same thing with a using statement.
    using (Font font2 = new Font("Arial", 10.0f))
    {
        byte charset = font2.GdiCharSet;
    }
    

Operadores && e ||&& and || Operators

  • Para evitar exceções e aumentar o desempenho ignorando comparações desnecessárias, use && em vez de & e || em vez de | ao executar comparações, conforme mostrado no exemplo a seguir.To avoid exceptions and increase performance by skipping unnecessary comparisons, use && instead of & and || instead of | when you perform comparisons, as shown in the following example.

    Console.Write("Enter a dividend: ");
    var dividend = Convert.ToInt32(Console.ReadLine());
    
    Console.Write("Enter a divisor: ");
    var divisor = Convert.ToInt32(Console.ReadLine());
    
    // If the divisor is 0, the second clause in the following condition
    // causes a run-time error. The && operator short circuits when the
    // first expression is false. That is, it does not evaluate the
    // second expression. The & operator evaluates both, and causes 
    // a run-time error when divisor is 0.
    if ((divisor != 0) && (dividend / divisor > 0))
    {
        Console.WriteLine("Quotient: {0}", dividend / divisor);
    }
    else
    {
        Console.WriteLine("Attempted division by 0 ends up here.");
    }
    

Operador NewNew Operator

  • Use um formulário conciso de instanciação de objeto com digitação implícita, conforme mostrado na declaração a seguir.Use the concise form of object instantiation, with implicit typing, as shown in the following declaration.

    var instance1 = new ExampleClass();
    

    A linha anterior é equivalente à declaração a seguir.The previous line is equivalent to the following declaration.

    ExampleClass instance2 = new ExampleClass();
    
  • Use inicializadores de objeto para simplificar a criação do objeto.Use object initializers to simplify object creation.

    // Object initializer.
    var instance3 = new ExampleClass { Name = "Desktop", ID = 37414, 
        Location = "Redmond", Age = 2.3 };
    
    // Default constructor and assignment statements.
    var instance4 = new ExampleClass();
    instance4.Name = "Desktop";
    instance4.ID = 37414;
    instance4.Location = "Redmond";
    instance4.Age = 2.3;
    

Tratamento de EventoEvent Handling

  • Se você estiver definindo um manipulador de eventos que não necessita ser removido posteriormente, use uma expressão lambda.If you are defining an event handler that you do not need to remove later, use a lambda expression.

    public Form2()
    {
        // You can use a lambda expression to define an event handler.
        this.Click += (s, e) =>
            {
                MessageBox.Show(
                    ((MouseEventArgs)e).Location.ToString());
            };
    }
    
    // Using a lambda expression shortens the following traditional definition.
    public Form1()
    {
        this.Click += new EventHandler(Form1_Click);
    }
    
    void Form1_Click(object sender, EventArgs e)
    {
        MessageBox.Show(((MouseEventArgs)e).Location.ToString());
    }
    

Membros EstáticosStatic Members

  • Chame membros estáticos usando o nome de classe: ClassName.StaticMember.Call static members by using the class name: ClassName.StaticMember. Essa prática torna o código mais legível, tornando o acesso estático limpo.This practice makes code more readable by making static access clear. Não qualifique um membro estático definido em uma classe base com o nome de uma classe derivada.Do not qualify a static member defined in a base class with the name of a derived class. Enquanto esse código é compilado, a leitura do código fica incorreta e o código poderá ser danificado no futuro se você adicionar um membro estático com o mesmo nome da classe derivada.While that code compiles, the code readability is misleading, and the code may break in the future if you add a static member with the same name to the derived class.

Consultas LINQLINQ Queries

  • Use nomes significativos para variáveis de consulta.Use meaningful names for query variables. O exemplo a seguir usa seattleCustomers para os clientes que estão localizados em Seattle.The following example uses seattleCustomers for customers who are located in Seattle.

    var seattleCustomers = from customer in customers
                           where customer.City == "Seattle"
                           select customer.Name;
    
  • Use aliases para se certificar de que os nomes de propriedades de tipos anônimos sejam colocados corretamente em maiúsculas, usando o padrão Pascal-Case.Use aliases to make sure that property names of anonymous types are correctly capitalized, using Pascal casing.

    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 propriedades no resultado forem ambíguos.Rename properties when the property names in the result would be ambiguous. Por exemplo, se a sua consulta retornar um nome de cliente e uma ID de distribuidor, em vez de deixá-los como Name e ID no resultado, renomeie-os para esclarecer que Name é o nome de um cliente, e ID é a identificação de um distribuidor.For example, if your query returns a customer name and a distributor ID, instead of leaving them as Name and ID in the result, rename them to clarify that Name is the name of a customer, and ID is the ID of a distributor.

    var localDistributors2 =
        from customer in customers
        join distributor in distributors on customer.City equals distributor.City
        select new { CustomerName = customer.Name, DistributorID = distributor.ID };
    
  • Usa a digitação implícita na declaração de variáveis de consulta e de intervalo.Use implicit typing in the declaration of query variables and range variables.

    var seattleCustomers = from customer in customers
                           where customer.City == "Seattle"
                           select customer.Name;
    
  • Alinhe cláusulas de consulta na cláusula from, conforme mostrado nos exemplos anteriores.Align query clauses under the from clause, as shown in the previous examples.

  • Use cláusulas where antes de outras cláusulas de consulta para garantir que cláusulas de consulta posteriores operem no conjunto de dados filtrado e reduzido.Use where clauses before other query clauses to ensure that later query clauses operate on the reduced, filtered set of data.

    var seattleCustomers2 = from customer in customers
                            where customer.City == "Seattle"
                            orderby customer.Name
                            select customer;
    
  • Use várias cláusulas from em vez de uma cláusula join para acessar coleções internas.Use multiple from clauses instead of a join clause to access inner collections. Por exemplo, cada coleção de objetos Student pode conter um conjunto de pontuações no teste.For example, a collection of Student objects might each contain a collection of test scores. Quando a próxima consulta for executada, ela retorna cada pontuação que seja acima de 90, juntamente com o sobrenome do estudante que recebeu a pontuação.When the following query is executed, it returns each score that is over 90, along with the last name of the student who received the score.

    // Use a compound from to access the inner sequence within each element.
    var scoreQuery = from student in students
                     from score in student.Scores
                     where score > 90
                     select new { Last = student.LastName, score };
    

SegurançaSecurity

Siga as diretrizes em Diretrizes de codificação segura.Follow the guidelines in Secure Coding Guidelines.

Consulte tambémSee also