practical csharp

C # pratique

Une collection de directives et de meilleures pratiques principalement raisonnables pour rédiger un code C # propre, lisible, compréhensible et maintenable.

Conventions de codage

Types

Utilisez var chaque fois approprié et possible

Objectif: meilleure lisibilité et propreté

BIEN

 var httpClient = new HttpClient ( ) ;

MAUVAIS

 HttpClient httpClient = new HttpClient ( ) ; 

---

Instanciation

Utiliser les initialiseurs d'objets sur l'affectation de la propriété directe

Objectif: meilleure lisibilité et propreté

BIEN

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

MAUVAIS

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

---

Chaînes littérales

Utiliser une interpolation de chaîne au lieu de string.Format

Objectif: meilleure lisibilité et sémantique

BIEN

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

MAUVAIS

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

Utilisez l'identifiant de chaîne motorisé le cas échéant

Objectif: Pas besoin de s'échapper des caractères de barre de barre

BIEN

 var path = @"C:UsersAdministratorDocuments" ;

MAUVAIS

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

Utilisez des constantes lorsque vous utilisez des littéraux de chaîne plus d'une fois

Objectif: le refactorisation peut devenir un cauchemar lorsque les littéraux de cordes sont distribués partout plusieurs fois

BIEN

 const string error = "user_not_found" ;

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

MAUVAIS

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

---

Appellation

Évitez les abréviations déraisonnables et les noms courts dénués de sens. Nous sommes en 2019 et tout le monde a l'achèvement du code. Veuillez ne pas dire que vous gagnez du temps en nommant vos variables xyz . C'est juste ridicule.

Objectif: le raccourcissement des noms de variables n'ajoute aucune valeur, il rend même Code beaucoup plus difficile à lire et à comprendre

BIEN

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

// Nice
var stringBuilder = new StringBuilder ( ) ;

// Nice
const string directorySeparator = "/" ;

MAUVAIS

 // 
var res = validator . Validate ( ) ;

// 
var sbd = new StringBuilder ( ) ;

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

Écrivez du code où le but et le type de membre peuvent être déduits de la sémantique

Objectif: rend le code extrêmement plus facile à lire, à maintenir et à travailler avec

BIEN

 //  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 )
  {
  }
}

MAUVAIS

 //  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 )
  {
  }
}

Évitez la redondance et fournissez des informations qui peuvent être déduites du contexte

Objectif: rend le code inutilement plus long et plus difficile à lire et à comprendre

BIEN

 // Clearly an interface
public interface IOrderManager { }

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

MAUVAIS

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

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

Écrivez du code qui s'explique, évitez les commentaires inutiles

Objectif: La pratique montre que les commentaires peuvent devenir obsolètes très facilement et rapidement à mesure que la base de code se développe et évolue. Le fait d'avoir une base de code explicite contribue à une meilleure maintenabilité et réduit la nécessité d'écrire et de maintenir des commentaires inutiles. (Cela ne signifie pas que l'écriture de commentaires est obsolète.)

BIEN

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

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

MAUVAIS

 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'utilisez pas toutes les lettres majuscules pour les abréviations

Objectif: cohérent avec le framework .NET et plus facile à lire

BIEN

 public class JsonParser { }

MAUVAIS

 public class JSONParser { }

Utilisez le singulier pour les noms de classe et d'énumération

Objectif: enum sont toujours abordés individuellement. Par exemple EmploymentTypes.FullTime EmploymentType.FullTime . De plus, les classes représentent toujours une seule instance d'un objet, par exemple un User individuel. Exception: Bit Field Enum

BIEN

 public enum EmploymentType
{
  FullTime ,
  PartTime
}

public class User
{

}

MAUVAIS

 public enum EmploymentTypes
{
  FullTime ,
  PartTime
}

public class Users
{

} 

---

Propriétés

Utilisez la définition du corps d'expression pour les propriétés en lecture

Objectif: sucre syntaxique ¯ (ツ) / ¯

BIEN

 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 ;
  }
}

MAUVAIS

 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 ;
  }
} 

---

Exceptions

Catch des exceptions aussi spécifiques que possible

But: meilleure conscience de ce qui n'a pas fonctionné. Permet plus de précision lors de la journalisation et de l'analyse des erreurs.

BIEN

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

MAUVAIS

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

Utilisez toujours des exceptions prédéfinies (le cas échéant) ou personnalisées, ne lancez jamais vous-même une Exception vous-même

Objectif: Très mauvaise pratique. Exception ne doivent être lancées que par le framework .NET.

BIEN

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

MAUVAIS

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

---

Membres privés

Utilisez un soulignement comme préfixe

Objectif: meilleure lisibilité

BIEN

 private string _username ;

MAUVAIS

 private string mUsername__ ;

// OR

private string username ;

// OR

private string username_ ; 

---

Espacement

N'ajoutez pas les lignes vides ou les espaces vides inutiles

Objectif: meilleure lisibilité, économise de l'espace

BIEN

 public class JsonParser
{
  private readonly string _json ;

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

MAUVAIS

 public class JsonParser
{

  private  readonly string  _json ;

  public JsonParser ( string json )
  {


    _json =    json ;
  }

} 

---

Immutabilité

Utilisez des propriétés Get uniquement (ReadOnly) dans la mesure du possible

Objectif: empêche les biens de changer accidentellement d'ailleurs, une meilleure prédiction du comportement de la demande

BIEN

 public class JsonParser
{
  public string Json { get ; }

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

MAUVAIS

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

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

Utilisez des collections ReadOnly dans la mesure du possible

Objectif: empêche la collecte d'être changée par ailleurs, une meilleure prédiction du comportement de l'application

BIEN

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

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

MAUVAIS

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

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

---

Usings

Utilisez toujours using de blocs

Objectif: la ressource est automatiquement éliminée lorsque le bloc using se termine

BIEN

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

}

MAUVAIS

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

Croisillons

Utilisez toujours des accolades

Objectif: meilleure lisibilité, maintenance plus facile lorsqu'une autre ligne est requise à l'intérieur de la condition

BIEN

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

MAUVAIS

 if ( user . IsElevated )
  // Do something

Meilleures pratiques

Enregistrement

Mettre en évidence les variables

Objectif: afin que vous sachiez quelle partie du message contient des variables.

BIEN

 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 ) ;
}

MAUVAIS

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

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

Ajoutez toujours des exceptions aux journaux d'erreur et utilisez la signature appropriée de l'enregistreur utilisé

Objectif: afin que l'exception puisse être filtrée dans certains cas (par exemple dans l'interface utilisateur, car la trace de pile entière est inutile pour l'utilisateur).

BIEN

 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 ) ;
}

MAUVAIS

 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 } " ) ;
}