Bienvenue à Blogs CodeS-SourceS Identification | Inscription | Aide

Aurélien GALTIER

The dark world of .Net

Coding is like Read

Aujourd'hui j'ai envie de sensibiliser les développeurs sur comment coder. C'est ambitieux et je sais que tout le monde ne sera pas d'accord avec moi sur la vision que j'ai du code. Ce que je vais dire par la suite, est pour certain du bon sens. Mais faite-moi confiance que beaucoup de société ne respecte pas toujours ce bon sens.

Pour cela on va partir d'un petit projet. Le code est disponible sur https://github.com/swoog/CodeCoding:

static void Main(string[] args)
{
   var j = new Jedi
   {
      Name = "Skywallker",
      FirstName = "Luke",
      Saber = new Saber(Color.Blue),
   };

   var dv = new Lord
   {
      Saber = new Saber(Color.Red),
   };

   var e = new Emperor();

   j.Saber.Severing(dv);

   e.Lightning(j, dv);

   var a = dv.To(firstName: "Anakin", name: "Skywalker");

   a.Kill(e);

   TE();
}

Ok on voie dans ce code que cela parle de Jedi, de Luke, Anakin, … Bref on est dans star wars mais on ne comprend rien.

Bien choisir ces noms de classes

Le choix du nom des classes est souvent fait rapidement. Ici on a une classe qui est nommé "Saber". Mais quel type de sabre ? Un sabre laser ?

Si vous nommé vos classe avec une convention claire on comprendra déjà plus ce qu'elles font. Dans mon cas je nommerai la classe LightSaber. Le jour ou voudrez mutualiser du code entre deux classe "Saber" vous pourrez appeler votre classe abstraite Saber (Ou AbstractSaber).

Pour ma part je respecte les conventions suivantes pour l'héritage :

Classe mère Service si c'est une classe abstraite AbstractService et pour la classe fille ProductService si c'est un service qui gère des produits.

Evité les abréviations. Les classes du style PrdSrv, ce n'est pas très claire. ProdServer ? ProductServer ? … Il sera plus facile de comprendre ce que fait une classe si l'on peut lire le nom sans être obligé de connaitre les abréviations. 

Les noms des propriétés

Maintenant que j'ai changé le nom de la classe. Je renommerais la propriété Saber en LightSaber. Effectivement la propriété est maintenant du type LightSaber.

Mais la deuxième propriété que je n'aime pas c'est "Name". Donc sur la classe on en déduit que Name est juste le nom de famille. Alors pourquoi pas le préciser. On renomme la propriété Name en LastName.

J'ai aussi sur la classe Jedi une propriété "Full". Au vue du code elle donne le nom complet du Jedi. Je propose de la nommer FullName.

public string Full
{
   get
   {
      return string.Format("{0} {1}", this.FirstName, this.Name);
   }

Les abréviations sont aussi à éviter pour les propriétés. J'ai déjà vue des cas d'abréviation qui ne veulent pas dire la même chose et qui sont différent à une seule lettre prêt (PrdhId et PrdId). Par contre effectivement on peut se fixer comme convention que Id est l'abréviation de Identifier. Mais n'abusez pas des abréviations pour tous. Car si je met les noms suivants :

PrdId
SrvId
UsrLog
Pwd
TxValue

C'est quand même plus lisible de mettre :

ProductId
ServiceId
UserLogin
Password
TaxValue

Nommer ces variables

Le nom des variables ce n'est pas important !!! Erreur

Certain aurais nommé la propriété "FullName" en "JediFullName".

Effectivement on obtiendrait :

j.JediFullName

C'est vrai que l'on comprend ce que cela renvois. Mais on ne sait pas trop ce qu'est "j"

Je pense que ce n'est pas la peine de répéter le nom de l'objet dans le nom des propriétés. On doit nommer correctement ces variables et le problème sera résolu. Si je fais :

var jedi = new Jedi{ FirstName = "Luke", LastName = "Skywalker" }
Console.WriteLine(jedi.FullName);
On comprend déjà mieux ce que l'on fait.

Mais on peut aller plus loin.

var luke = new Jedi{ FirstName = "Luke", LastName = "Skywalker" }
Console.WriteLine(luke.FullName);


Effectivement on manipule une instance de la classe Jedi et c'est même Luke

Je ne rentrerais pas dans le débat du mot clef var. Est-ce que c'est bien de mettre var ou pas ? Moi je n'ai pas d'avis tranché sur la question. Je mets naturellement le mot clef var dans mes applications. Maintenant je pense que si le code est propre et lisible il n'y a pas de problème à comprendre le type de la variable.

Le nom des méthodes

Pour le nom des méthodes aussi il faut faire attention.

Ma convention c'est chaque mot avec la première lettre en majuscule. Évitez les abréviations. Utilisez des conventions pour tous ce qui est CRUD. Tel que :

GetProduct, InsertProduct, UpdateProduct, DeleteProduct.

Si votre méthode renvois plusieurs produits alors utilisez GetProducts.

Vous pouvez aussi utiliser les mots clefs : From,To, Of, At, …

Dans notre exemple on peut faire luke.LightSaber.SeveringOf(lord) Et on peut même préciser quoi luke.LightSaber.SeveringHandOf(lord)

Dans cette exemple on comprend bien ce qui ce passes.

De la même manière je ferais

emperor.UseLightningForceOn(luke, lord)

Dans certain cas cela fait un nom de méthode très grand. Mais je trouve c'est plus lisible. Si j'utilise des abréviations encore une foi j'obtiens quelque chose comme :

emperor.UseLghtForceOn(luke, lord)

Lght ? Light Force ?

Pour décider du nom d'une méthode comme pour le nom d'une classe, vous pouvez faire appel à votre équipe. Il est toujours bon quand vous avez à fixer le nom d'une classe ou méthode importante de faire un vote avec propositions. Chacun propose un ou plusieurs noms et vous votez. Avantage vous aurez peut-être pas eu l'idée du nom et ce nouveau nom sera connus de tout le monde. Par contre il ne faut pas non plus que cela prennent l'après-midi pour décider du nom.

TheEnd

Pour finir la méthode TE à la fin du programme peut être renommé en TheEnd() Ce qui donne le code suivant:

static void Main(string[] args)
{
    var luke = new Jedi
    {
        LastName = "Skywallker",
        FirstName = "Luke",
        LightSaber = new LightSaber(Color.Blue),
    };

    var darkVador = new Lord
    {
        LightSaber = new LightSaber(Color.Red),
    };

    var emperorSith = new Emperor();

    luke.LightSaber.SeveringHandOf(darkVador);

   
emperorSith.UseForceLightningTo(luke, darkVador);

   
var anakin = darkVador.To(firstName: "Anakin", lastName: "Skywalker");

   
anakin.Kill(emperorSith);

   
TheEnd();
}

On comprend mieux ce que fait le code il raconte le duel de Luke et dark vador contre l'empereur Sith. Pour le fun l'exécution du programme donne comme résultat:

Luke Skywallker severing hand of Dark Vador
Sith emperor use force lightning on Luke Skywallker and Dark Vador
Anakin Skywalker reemerges
Anakin Skywalker kill Sith Emperor

Un dernier point, est le choix des noms français ou anglais ? Moi je penche pour l'anglais. Si je prends le français, avec une méthode qui renvois des produits on obtient "GetProduits" normalement il serait plus correcte de dire "ObtientProduits". Pour ma part je préfère écrire "GetProducts". Mais je pense que c'est un choix important dans la nomenclature du code. Évité les mélange français/anglais.

J'ai fait ce code exprès sans commentaire et on peut voir que même sans commentaire il est compréhensible. D'une manière générale il faut faire du code qui pourra être lus par un nouveau développeur sur le projet. Ainsi le code sera auto documenté.

Ce post vous a plu ? Ajoutez le dans vos favoris pour ne pas perdre de temps à le retrouver le jour où vous en aurez besoin :
Posted: mardi 1 juillet 2014 15:30 par agaltier
Classé sous :

Commentaires

Pas de commentaires

Les commentaires anonymes sont désactivés

Les 10 derniers blogs postés

- Merci par Blog de Jérémy Jeanson le 10-01-2019, 20:47

- Office 365: Script PowerShell pour auditer l’usage des Office Groups de votre tenant par Blog Technique de Romelard Fabrice le 04-26-2019, 11:02

- Office 365: Script PowerShell pour auditer l’usage de Microsoft Teams de votre tenant par Blog Technique de Romelard Fabrice le 04-26-2019, 10:39

- Office 365: Script PowerShell pour auditer l’usage de OneDrive for Business de votre tenant par Blog Technique de Romelard Fabrice le 04-25-2019, 15:13

- Office 365: Script PowerShell pour auditer l’usage de SharePoint Online de votre tenant par Blog Technique de Romelard Fabrice le 02-27-2019, 13:39

- Office 365: Script PowerShell pour auditer l’usage d’Exchange Online de votre tenant par Blog Technique de Romelard Fabrice le 02-25-2019, 15:07

- Office 365: Script PowerShell pour auditer le contenu de son Office 365 Stream Portal par Blog Technique de Romelard Fabrice le 02-21-2019, 17:56

- Office 365: Script PowerShell pour auditer le contenu de son Office 365 Video Portal par Blog Technique de Romelard Fabrice le 02-18-2019, 18:56

- Office 365: Script PowerShell pour extraire les Audit Log basés sur des filtres fournis par Blog Technique de Romelard Fabrice le 01-28-2019, 16:13

- SharePoint Online: Script PowerShell pour désactiver l’Option IRM des sites SPO non autorisés par Blog Technique de Romelard Fabrice le 12-14-2018, 13:01