practical csharp

C# prático

Uma coleção de diretrizes e práticas recomendadas principalmente razoáveis ​​para escrever código C# limpo, legível, compreensível e sustentável.

Convenções de codificação

Tipos

Use var sempre que apropriado e possível

Objetivo: melhor legibilidade e limpeza

BOM

 var httpClient = new HttpClient ( ) ;

RUIM

 HttpClient httpClient = new HttpClient ( ) ; 

---

Instanciação

Use Inicializadores de Objeto sobre a atribuição de propriedade direta

Objetivo: melhor legibilidade e limpeza

BOM

 var user = new User
{
  Username = "admin" ,
  Age = 31
} ;

RUIM

 var user = new User ( ) ;
user . Username = "admin" ;
user . Age = 31 ; 

---

Literais de cordas

Use interpolação de string em vez de string.Format

Objetivo: melhor legibilidade e semântica

BOM

 var url = "http://localhost/api" ;
var resource = "users" ;
var path = $ " { url } / { resource } " ;

RUIM

 var url = "http://localhost/api" ;
var resource = "users" ;
var path = string . Format ( "{0}/{1}" , url , resource ) ;

Use o identificador de string literal, quando apropriado

Objetivo: Não há necessidade de escapar dos personagens de barra de barriga

BOM

 var path = @"C:UsersAdministratorDocuments" ;

RUIM

 var path = "C: \ Users \ Administrator \ Documents" ;

Use constantes ao usar literais de cordas mais de uma vez

Objetivo: a refatoração pode se tornar um pesadelo quando os literais de cordas são distribuídos por todo o lugar várias vezes

BOM

 const string error = "user_not_found" ;

Log . Error ( error ) ;
return BadRequest ( error ) ;

RUIM

 Log . Error ( "user_not_found" ) ;
return BadRequest ( "user_not_found" ) ; 

---

Nomeação

Evite abreviações irracionais e nomes curtos sem sentido. É 2019 e todo mundo tem conclusão de código. Por favor, não diga que você está economizando tempo nomeando suas variáveis xyz . É apenas ridículo.

Objetivo: Os nomes de variáveis ​​de encurtamento não agregam valor, ele ainda torna o código muito mais difícil de ler e entender

BOM

 // Nice
var validationResult = validator . Validate ( ) ;

// Nice
var stringBuilder = new StringBuilder ( ) ;

// Nice
const string directorySeparator = "/" ;

RUIM

 // 
var res = validator . Validate ( ) ;

// 
var sbd = new StringBuilder ( ) ;

//  Seriously?
const string dsep = "/" ;

Escreva o código onde o objetivo e o tipo de membro podem ser inferidos da semântica

Objetivo: torna o código tremendamente mais fácil de ler, manter e trabalhar com

BOM

 //  The purpose of this class can be easily inferred
public class OrderManager
{
  //  Using "Is" or "Has" as prefix clearly indicates that a method returns a boolean value
  public bool IsFulfilled ( Order order ) 
  {
  }

  public bool HasPositions ( Order order )
  {
  }

  //  Using a verb clearly indicates that a method performs some action
  public void ProcessOrder ( Order order )
  {
  }

  public void CancelOrder ( Order order )
  {
  }
}

RUIM

 //  Purpose of this class can not be easily inferred
public class OrderHelper
{
  //  Unclear
  public bool Fulfilled ( Order order ) 
  {
  }

  //  Unclear => users would likely expect a method that retrieves the positions of the order due to the verb "Get"
  public bool GetPositions ( Order order )
  {
  }

  //  Unclear
  public void Order ( Order order )
  {
  }

  //  Unclear
  public void StopOrder ( Order order )
  {
  }
}

Evite redundância e fornecimento de informações que possam ser inferidas do contexto

Objetivo: Torna o código desnecessariamente mais longo e mais difícil de ler e entender

BOM

 // Clearly an interface
public interface IOrderManager { }

// Clearly a list of orders
private IList < Order > orders ;

RUIM

 // Clearly an interface => no "Interface" postfix necessary
public interface IOrderManagerInterface { }

// Clearly a list of oders => no "List" postfix necessary
private IList < Order > orderList ;

Escreva código auto-explicativo, evite comentários desnecessários

Objetivo: A prática mostra que os comentários podem ficar desatualizados com muita facilidade e rapidez à medida que a base de código cresce e evolui. Ter uma base de código auto-explicativa contribui para melhorar a manutenção e reduz a necessidade de escrever e manter comentários não-terminados. (Isso não significa que escrever comentários é obsoleto.)

BOM

 public class OrderManager 
{
  public void ProcessOrder ( Order order ) 
  {
    var items = order . GetItems ( ) ;

    foreach ( var item in items ) 
    {
      var availability = item . GetAvailability ( ) ;
    }
  }
}

RUIM

 public class OrderManager 
{
  public void ExecuteOrder ( Order order ) 
  {
    // Get all available items from the order
    var data = order . GetData ( ) ;

    foreach ( var x in data ) 
    {
      // Determine the availability of the item
      var available = item . CheckAvailability ( ) ;
    }
  }
}

Não use todas as letras maiúsculas para abreviações

Objetivo: consistente com a estrutura .NET e mais fácil de ler

BOM

 public class JsonParser { }

RUIM

 public class JSONParser { }

Use singular para nomes de classe e enum

Objetivo: enum s é sempre abordado individualmente. Por exemplo, EmploymentType.FullTime é muito mais limpo que EmploymentTypes.FullTime . Além disso, as classes sempre representam uma única instância de um objeto, por exemplo, um User individual. Exceção: enumes de campo de bit

BOM

 public enum EmploymentType
{
  FullTime ,
  PartTime
}

public class User
{

}

RUIM

 public enum EmploymentTypes
{
  FullTime ,
  PartTime
}

public class Users
{

} 

---

Propriedades

Use a definição de corpo de expressão para propriedades readonly

Objetivo: açúcar sintático ¯ (ツ) /¯

BOM

 public class User
{
  public string Username { get ; }
  public int Age { get ; }

  public string DisplayName => $ " { Username } ( { Age } )" ;

  public User ( string username , int age )
  {
    Username = username ;
    Age = age ;
  }
}

RUIM

 public class User
{
  public string Username { get ; }
  public int Age { get ; }

  public string DisplayName
  {
    get
    {
      return $ " { Username } ( { Age } )" ;
    }
  }

  public User ( string username , int age )
  {
    Username = username ;
    Age = age ;
  }
} 

---

Exceções

Capturar exceções o mais específico possível

Objetivo: Melhor consciência do que deu errado. Permite mais precisão durante a análise de registro e erro.

BOM

 try
{
  System . IO . File . Open ( path ) ;
}
catch ( FileNotFoundException ex )
{
  // Specific
}
catch ( IOException ex )
{
  // Specific
}
catch ( Exception ex )
{
  // Default
}

RUIM

 try
{
  System . IO . File . Open ( path ) ;
}
catch ( Exception ex )
{
  // SOMETHING went wrong
}

Sempre use exceções predefinidas (se aplicável) ou personalizadas, nunca faça uma Exception

Objetivo: prática muito ruim. Exception s deve ser jogada apenas pela estrutura .NET.

BOM

 public void ProcessOrder ( Order order )
{
  if ( order == null )
  {
    throw new ArgumentNullException ( nameof ( order ) ) ;
  }
}

RUIM

 public void ProcessOrder ( Order order )
{
  if ( order == null )
  {
    throw new Exception ( "Order is null." ) ;
  }
} 

---

Membros particulares

Use um sublinhado como prefixo

Objetivo: Melhor legibilidade

BOM

 private string _username ;

RUIM

 private string mUsername__ ;

// OR

private string username ;

// OR

private string username_ ; 

---

Espaçamento

Não adicione linhas vazias desnecessárias ou espaços em branco

Objetivo: melhor legibilidade, salva o espaço

BOM

 public class JsonParser
{
  private readonly string _json ;

  public JsonParser ( string json )
  {
    _json = json ;
  }
}

RUIM

 public class JsonParser
{

  private  readonly string  _json ;

  public JsonParser ( string json )
  {


    _json =    json ;
  }

} 

---

Imutabilidade

Use propriedades apenas para obter (readonly) sempre que possível

Objetivo: impede que a propriedade seja alterada acidentalmente de outros lugares, melhor previsão do comportamento do aplicativo

BOM

 public class JsonParser
{
  public string Json { get ; }

  public JsonParser ( string json )
  {
    Json = json ;
  }
}

RUIM

 public class JsonParser
{
  public string Json { get ; set ; }

  public JsonParser ( string json )
  {
    Json = json ;
  }
}

Use coleções readonly sempre que possível

Objetivo: impede a coleção de ser alterada de outros lugares, melhor previsão do comportamento do aplicativo

BOM

 public class KeywordProvider
{
  public IReadOnlyCollection < string > Keywords { get ; }

  public KeywordProvider ( )
  {
    Keywords = new ReadOnlyCollection < string > ( new List < string >
    {
      "public" ,
      "string"
    } ) ;
  }
}

RUIM

 public class KeywordProvider
{
  public IList < string > Keywords { get ; }

  public KeywordProvider ( )
  {
    Keywords = new List < string >
    {
      "public" ,
      "string"
    } ;
  }
} 

---

Usings

Sempre use using blocos

Objetivo: o recurso é descartado automaticamente quando o using do bloco acaba

BOM

 using ( var connection = new SqlConnection ( connectionString ) )
{

}

RUIM

 try
{
  var connection = new SqlConnection ( connectionString ) ;
}
finally
{
  connection . Close ( ) ;
  connection . Dispose ( ) ;
} 

Aparelho ortodôntico

Sempre use aparelhos

Objetivo: melhor legibilidade, manutenção mais fácil quando outra linha é necessária dentro da condição

BOM

 if ( user . IsElevated )
{
  // Do something
}

RUIM

 if ( user . IsElevated )
  // Do something

Práticas recomendadas

Log

Destaque variáveis

Objetivo: para que você esteja ciente de qual parte da mensagem contém variáveis.

BOM

 var filePath = @"C:tmpmy-file.txt" ;

try 
{
  var file = File . Open ( filePath ) ;
}
catch ( Exception ex )
{
  // GOOD: Add [ ] to the variable
  Log . Error ( $ "Could not open file [ { filePath } ]." , ex ) ;
}

RUIM

 var filePath = @"C:tmpmy-file.txt" ;

try 
{
  var file = File . Open ( filePath ) ;
}
catch ( Exception ex )
{
  Log . Error ( $ "Could not open file { filePath } ." , ex ) ;
}

Sempre adicione exceções aos logs de erros e use a assinatura apropriada do logger usado

Objetivo: para que a exceção possa ser filtrada em certos casos (por exemplo, na interface do usuário, pois todo o rastreamento da pilha é inútil para o usuário).

BOM

 try 
{
  var file = File . Open ( @"C:tmpmy-file.txt" ) ;
}
catch ( Exception ex )
{
  // Use appropriate signature of your logger to include the exception as separate parameter
  Log . Error ( "Could not open file." , ex ) ;
}

RUIM

 try 
{
  var file = File . Open ( @"C:tmpmy-file.txt" ) ;
}
catch ( Exception ex )
{
  // Strictly AVOID this. The exception is added directly to the log message, which makes it impossible to filter the exception
  Log . Error ( $ "Could not open file: { ex } " ) ;
}