À la pointe

Conseils relatifs à la lisibilité du code source

Dino Esposito Avez-vous jamais entendu parler de l'International Obfuscated C Code Contest ? En un mot, c'est un concours ouvert qui sélectionne un gagnant dans une poignée de programmes C qui résout un problème — aucun problème — avec un code C extrêmement obscur et obscurci. Vous pouvez trouver le code source de gagner des programmes des années précédentes à ioccc.org/years.html.

L'Obfuscated C Code Contest est une façon enjouée pour démontrer l'importance du style et de la lisibilité dans la programmation. Cette colonne résume certaines des pratiques plus importantes que vous aurez envie de suivre afin d'avoir le code qui est facile à lire et à comprendre — aussi bien pour votre propre bien et celui de vos collègues.

Lisibilité en tant qu'attribut

En développement de logiciel, maintenabilité est l'attribut qui fait référence à la facilité avec laquelle vous pouvez modifier le code existant pour atteindre des objectifs tels que corriger un bogue, entretien ménager, mise en œuvre d'une nouvelle fonctionnalité ou juste refactorisation pour certains modèles. Maintenabilité est l'un des attributs fondamentaux du logiciel, selon le document ISO/IEC 9126. Pour plus d'informations sur les attributs du logiciel, reportez-vous au livre à bit.ly/VCpe9q.

Résultats de maintenabilité du code d'une variété de facteurs, dont est la lisibilité. Le code qui est difficile à lire est aussi difficile à comprendre. Les développeurs qui ont mis leurs mains sur elles ne clairement connaître et comprendre le code sont susceptibles de rendre le code encore pire.

Malheureusement, la lisibilité est une question très subjective. Il est pratiquement impossible de mettre au point un outil automatique afin de vérifier et de signaler au niveau de la lisibilité du code. Cependant, même si la mesure automatique de lisibilité était possible, tout ces outils seraient probablement considéré comme très peu fiables et ne soit approuvés par tout le monde. En fin de compte, lisibilité est un attribut manuel que les développeurs indépendants devraient vérifier avec le reste de leur code. La capacité d'écrire du code qui est facile à lire doit faire partie de la responsabilité culturelle de développeurs individuels, s'étendant à l'ensemble de leurs compétences.

De manière générale, la lisibilité est un attribut de code, vous pouvez et devriez apprendre à adopter dès le début de votre carrière de programmation et de développer et d'améliorer au fil du temps. Comme style et bonne conception, lisibilité ne devrait pas être réservée aux experts. Plus important, il ne devrait pas être reporté à lorsque vous avez juste assez de temps pour elle.

Une approche pragmatique à la lisibilité

Produisant du code lisible est une question de respect pour les autres développeurs. Comme un utilisateur de StackOverflow une fois posté, « vous devriez toujours coder comme si la personne qui finit par maintenir votre code est un psychopathe violent qui sait où vous habitez. » Vous devriez également considérer le développeur qui finit par maintenir que votre code, un jour, peut-être vous.

Lors de la lecture de code d'autres personnes, il y a quelques choses qui peuvent vous rendre fou. Un aspect qui le rend difficile à lire le code est des structures de données et algorithmes avec aucun des objectifs clairs. Un autre aspect est peu claires stratégies utilisées dans le code qui sont difficiles à déterminer et pas bien notés par le biais de commentaires. Voici un exemple :

// Find the smallest number in a list of integers
private int mininList(params int[] numbers)
{
  var min = Int32.MaxValue;
  for (var i = 0; i < numbers.length; i++) {
    int number = numbers[i];
    if (number < min)
      min = number;
  }
  return min;
}

Même si j'ai porté l'exemple en c# pour plus de clarté, je dois admettre que ce n'est pas un morceau de code que n'importe quel développeur c# envisagerait jamais écrit. La raison est qu'avec c# et Microsoft .NET Framework, vous pouvez obtenir beaucoup de mêmes résultats à l'aide de LINQ. J'ai rencontré un code similaire dans un projet, sauf qu'il a été écrit en Java. À un certain moment, j'ai été embauché à la base de code pour le Framework .NET et c# de port.

Vous pourriez également trouver code comme ça dans un projet .NET réel. Vous pouvez appliquer certaines considérations de lisibilité sans perdre votre intention. La première chose qui ne fonctionne pas de cette fonction est le nom. La convention est discutable. Le nom manque un verbe et utilise une logique de casse mixte. Quelque chose comme GetMinFromList aurait probablement été un meilleur nom. Toutefois, le point plus discutable du code est le qualificateur privé utilisé dans le nom.

N'importe quel lecteur occasionnel de ce code peut voir que la fonction sert un utilitaire. En d'autres termes, elle représente un élément potentiellement réutilisable de code, que vous pouvez appeler à partir d'une variété d'endroits dans le reste de la base de code. Par conséquent, le marquant comme privé n'est pas toujours sensé. Cependant, les développeurs connaissent la puissance de la règle YAGNI — vous Ain't besoin il va — et, raisonnablement, tendance de ne pas exposer le code qui n'est pas strictement nécessaire.

L'auteur de ce code pourrait avoir prévu la fonction comme potentiellement réutilisables, mais pas quand il a été écrit. C'est pourquoi que la fonction a été écrite pour être facilement transformée en une fonction d'assistance réutilisables, mais a été marquée privée pour être visible uniquement dans la classe de l'hôte. Cette stratégie de codage peut être difficile de comprendre immédiatement pour les lecteurs externes. Cependant, c'est juste une décision qui nécessite quelques lignes de commentaires pour expliquer sa motivation. Si vous n'ajoutez pas de commentaires appropriés, vous n'êtes pas être un bon citoyen dans le monde de codage. Lecteurs finalement donner un sens, mais il gaspille quelques minutes et, pire encore, il rend les lecteurs quelque peu hostile à l'auteur.

Règles pratiques de lisibilité

Lisibilité du code est l'un de ces sujets dont l'importance est largement reconnue, mais pas nécessairement formalisé. Dans le même temps, sans une certaine formalisation, la lisibilité du code est presque un concept vide. Dans l'ensemble, vous pouvez approcher la lisibilité avec la règle des trois C : la fonction combinée des commentaires, de cohérence et de clarté.

Outils de l'IDE sont beaucoup plus intelligents aujourd'hui qu'il y a quelques années. Les développeurs n'ont aucun stricte nécessaire d'écrire des fichiers d'aide et d'intégrer leur documentation personnalisée dans les projets de Visual Studio . Info-bulles sont créées partout et automatiquement des commentaires. IDEs modernes rendent si facile à définir commentaires institutionnels, tout ce que vous devez penser d'est le texte et l'IDE fera le reste. Un commentaire institutionnel est le commentaire classique vous ajoutez aux méthodes et classes pour fournir une description concise des objectifs. Vous devriez écrire ces commentaires qui ont suivi les normes de plate-forme ou de la langue. Vous devriez également considérer ces commentaires obligatoire pour tout public morceau de code que vous créez.

L'interdiction de commentaires évidentes est une autre étape fondamentale sur la route pour améliorer la lisibilité. Commentaires évidents simplement ajouter de bruit et aucune information pertinente. Par définition, un commentaire est un texte explicatif pour toute décision que vous prenez dans le code qui n'est pas immédiatement évident. Un commentaire ne devrait être qu'une remarque perspicace sur un aspect particulier du code.

Le deuxième « C » est la cohérence. Chaque équipe a besoin d'utiliser les mêmes lignes directrices pour l'écriture de code. C'est encore mieux si ces lignes directrices sont utilisés sur une base de l'échelle de l'entreprise. Quand il s'agit de lignes directrices, nombreux arrêt au point de définir quelles directives devrait être et arrêter d'essayer de comprendre ce qui est juste et ce qui ne va pas. J'ose dire que tort ou raison est un point secondaire par rapport à l'importance de toujours faire la même chose de la même façon tout au long de votre code.

Supposons un instant que vous écrivez une bibliothèque qui string manipulation. À plusieurs endroits au sein de cette bibliothèque, vous devrez probablement vérifier si une chaîne contient une sous-chaîne donnée. Comment tu fais ça ? Dans le .NET Framework, ainsi que le Java SDK, vous avez au moins deux façons d'atteindre le même résultat. Vous pouvez utiliser la méthode Contains ou IndexOf. Ces deux méthodes, cependant, ont des objectifs différents.

La méthode Contains retourne une réponse booléenne et vous indique juste savoir si la sous-chaîne est contenue dans une chaîne donnée. La méthode IndexOf retourne l'index de base zéro où se trouve la chaîne recherchée. S'il n'y a aucune sous-chaîne, IndexOf retourne -1. D'un point de vue purement fonctionnel, donc, vous pouvez utiliser Contains et IndexOf pour atteindre les mêmes objectifs.

Cependant, ils donnent un message différent à personne de lire le code et les forces au lecteur de prendre une seconde passe sur le code pour voir s'il y a une raison particulière d'utiliser IndexOf au lieu de Contains. Un second passage unique lecture sur une ligne de code n'est pas un problème, bien sûr. Mais quand il arrive sur une base de code entier de milliers de lignes de code, il a d'incidence sur le temps et, par la suite, les coûts. C'est le coût direct de ne pas avoir de code très lisible.

Un sentiment de cohérence du code devrait faire partie de votre responsabilité d'inné. En tant que développeur, vous devriez viser à écrire du code pur la première fois sans l'espoir d'avoir assez de temps pour le nettoyer plus tard. Chef d'équipe, vous devriez appliquer les directives de cohérence du code par le biais de stratégies d'archivage. Idéalement, vous ne devrait pas permettre à check-in de n'importe quel code qui ne passe pas un test de cohérence.

La dernière version de ReSharper peut être une aide considérable pour rendre cette idée concrète. Vous pouvez utiliser ces outils de ligne de commande gratuits — un ensemble autonome d'outils — d'intégrer des formulaires d'analyse de la qualité du code directement dans votre intégration continue (CI) ou un système de contrôle de version. Ces outils de ligne de commande peuvent effectuer des inspections de code en mode hors connexion. Il s'agit de la même série de code, vous pouvez effectuer des inspections vivent dans Visual Studio avec ReSharper installé pour intercepter les doublons dans votre code. Selon vos fonctionnalités de personnalisation de CI, vous devrez envelopper les outils de ligne de commande dans un composant spécial. Pour plus d'informations sur ReSharper, Découvrez bit.ly/1avsZ2R.

La troisième et dernière « C » de la lisibilité du code est la clarté. Votre code est clair, si vous le style d'une manière qu'il se lit bien et facilement. Cela inclut la nidification et regroupement approprié. En général, les instructions IF ajoutent beaucoup de bruit au code. Parfois, vous ne pouvez éviter les instructions conditionnelles — un pilier des langages de programmation, mais essayant de limiter le nombre d'instructions IF garde nichant sous contrôle et rend le code plus facile à lire. Vous pouvez également utiliser un IF... D'AUTRE... IF... D'autre structure plutôt que les instructions IF imbriquées.

Certaines tâches peuvent nécessiter quelques lignes de code et il pourrait être difficile ou simplement inapproprié de faire un « Extraire la méthode » refactorisation. Dans ce cas, il est bon de garder ces lignes dans des blocs séparés par des lignes vides. Il ne change pas la substance du code, mais il maintient plus facile à lire. Enfin, si vous cherchez de l'inspiration sur la manière de votre code source de style, jetez un oeil à certains projets open source.

Bref, vaut mieux

Lignes plus longues, il est difficile pour l'oeil humain à lire. C'est pourquoi leur texte dans les colonnes d'impression des journaux et magazines. Quand il s'agit de votre code, vous devriez faire la même chose et limiter la longueur horizontale de lignes tant le défilement vertical des méthodes. Quelle est la durée idéale du corps de la méthode ? Généralement, les 30 lignes doivent être un niveau maximal qui déclenche une sonnette d'alarme et suggère que vous envisager de refactorisation. Enfin, une bonne organisation de dossiers de projet et le couplage entre les dossiers et les espaces de noms souvent reflète une bonne organisation des éléments de code individuel.

Lorsque vous soulevez le thème du code propre et de lisibilité, vous êtes souvent exposé à une objection commune — écriture de code propre est difficile et prend beaucoup de temps. Vous devriez essayer de neutraliser ce point de vue, et il y a deux façons que vous pouvez. Une consiste à utiliser un outil assistant de code qui permet d'écrire du code propre en suggérant refactorings, inspecte votre code pour les mauvaises habitudes et vérification de code dupliqué ou mort. Si vous pouvez faire toutes ces fonctionnalités accessibles, il faut vraiment pas plus d'excuses pour ne pas écrire un code plus propre et lisible. Outils assistant code sont offerts à partir de grands fournisseurs. Sélectionner tout, mais en choisir un.

L'autre est d'accentuer l'auto-amélioration et l'attitude de votre aux développeurs d'écrire du code plus propre comme une question de pratique générale. Les développeurs expérimentés cela bien. La capacité de savoir à peu près quelle distance vous êtes de la version finale de votre code et puis vraiment Nettoyez, est des principales caractéristiques qui sépare les moins expérimentés dans les développeurs expérimentés.

Dino Esposito est le co-auteur de « Microsoft .NET : Conception d'Applications pour l'entreprise » (Microsoft Press, 2014) et "programmation ASP.NET MVC 5" (Microsoft Press, 2014). Un spécialiste technique pour le .NET Framework et les plates-formes Android à JetBrains et lors des événements de l'industrie dans le monde entier, Esposito partage sa vision du logiciel à software2cents.wordpress.com et sur Twitter à twitter.com/despos.

Merci à l'expert technique Microsoft suivant d'avoir relu cet article : James McCaffrey

Partager via