Comment sauriez-vous si vous avez écrit du code lisible et facilement maintenable?

Comment savoir si le code créé est facilement lisible, compréhensible et maintenable? Bien sûr, du point de vue de l'auteur, le code est lisible et maintenable, car l'auteur l'a écrit et l'a édité, pour commencer. Cependant, il doit exister un standard objectif et quantifiable selon lequel notre profession peut mesurer le code.

Ces objectifs sont atteints lorsque l’on peut faire ce qui suit avec le code sans les conseils éclairés de l’auteur original:

• Il est possible de lire le code et de comprendre à un niveau élémentaire le flux de la logique.

• Il est possible de comprendre plus profondément ce que fait le code pour inclure les entrées, les sorties et les algorithmes.

• D'autres développeurs peuvent apporter des modifications significatives au code d'origine, telles que des corrections de bugs ou un refactoring.

• On peut écrire un nouveau code tel qu'une classe ou un module qui exploite le code d'origine.

Comment quantifier ou mesurer la qualité du code afin de le savoir lisible, compréhensible et maintenable?

Votre pair vous dit après avoir examiné le code.

Vous ne pouvez pas le déterminer vous-même car, en tant qu'auteur, vous en savez plus que le code ne le dit. Un ordinateur ne peut pas vous dire, pour les mêmes raisons qu'il ne peut pas savoir si un tableau est un art ou non. Par conséquent, vous avez besoin d'un autre humain capable de gérer le logiciel pour examiner ce que vous avez écrit et donner son opinion. Le nom officiel de ce processus est l'examen par les pairs .

Parfois, la meilleure façon de savoir est de revenir au code que vous avez écrit il y a six mois et d'essayer de comprendre ce pour quoi il a été écrit.

Si vous comprenez vite - c'est lisible.

Il est:

1. maintenable si vous pouvez le maintenir .
2. facilement maintenable si quelqu'un d'autre peut le maintenir sans vous demander de l'aide
3. lisible si quelqu'un d'autre , en le lisant, comprend correctement le design, la mise en page et l'intention

Le vrai test pour 1. est (comme le disent Alex à Paris et quant_dev ) que vous pouvez le récupérer après quelques mois pour faire autre chose.

Le test pour 2. et 3. est que quelqu'un d'autre peut le récupérer et déterminer comment étendre ou corriger votre code tout en suivant le fil de votre conception. S'ils ne peuvent pas comprendre la conception, son lien avec l'espace du problème ou la manière dont votre code est destiné à être utilisé, ils vont plutôt pirater une solution.

Il y a des règles empiriques, des principes (c.-à-d. Des règles empiriques, une personne a bien écrit et donné un nom) et toutes sortes de suggestions qui peuvent vous guider dans la bonne direction ou vous écarter des pièges courants. Aucun d'entre eux ne garantira les qualités que vous demandez, cependant.

Si votre code suit les principes de SOLID et DRY et comporte de nombreux tests unitaires, il est probablement maintenable.

Est-ce lisible? Lis le. Les noms de méthodes et de variables ont-ils un sens? Pouvez-vous suivre la logique du programme sans problème? Si la réponse est oui, alors le code est lisible.

Lire comment écrire un code invraisemblable - Assurez un emploi pour la vie par Roedy Green, en riant et en apprenant.

... comment écrire un code si difficile à gérer que les personnes qui vous suivront mettront des années à effectuer les changements les plus simples. De plus, si vous respectez toutes ces règles de manière religieuse, vous vous garantissez même une vie de travail, puisque personne d'autre que vous n'a l'espoir de maintenir le code ...

L'essai vous donne de nombreux exemples sur la façon d'écrire un mauvais code, en utilisant beaucoup d'exemples amusants. Il continue d'expliquer comment utiliser Creative Miss-Spelling , Reuse of Names , technique très appréciée de la réutilisation de noms globaux privés .

De manière humoristique, l’essai vous apprend à éviter tous les exemples de code illisible et incontrôlable.

En fait, j'ai eu du mal à croire que quelqu'un écrive un code avec des similitudes avec les exemples du texte. C'était quand je venais de sortir de l'école. Mais après quelques années de travail, je vois chaque jour le code du texte…

Malgré les apparences, il existe des mesures assez objectives que vous pouvez envisager. Des ouvrages tels que Normes de codage C ++ , Refactoring et Clean Code ont une longue liste de critères permettant de juger votre code: noms significatifs, tailles de fonctions, principes tels que couplage et cohésion, conception d'objet, tests unitaires, raffinements successifs, etc.

La liste est trop longue pour faire l’objet d’une liste de contrôle, mais vous devez lire le livre et choisir quelques éléments clés sur lesquels vous allez travailler, puis le relire après plusieurs mois pour le perfectionner davantage.

La preuve est dans le pudding. Regardez ce qui se passe après avoir remis le document à une personne raisonnablement compétente. S'ils n'ont pas besoin de poser beaucoup de questions sur la difficulté du code, vous avez fait du bon travail.

Ce fut une des premières leçons de ma carrière. Un mentor a déclaré: "Tout documenter, pour que vous puissiez échapper au programme plus tard. Si vous ne prévoyez pas de questions lorsque les réponses sont fraîches dans votre esprit, vous devrez les comprendre quand elles ne le seront pas."

J'ai lu toutes les réponses et j'ai remarqué que personne ne mentionnait la complexité du code.

Il existe une étroite corrélation entre la complexité du code et la lisibilité / maintenabilité. Il existe de nombreux algorithmes d'évaluation de la complexité du code, mais je parlerai simplement de la façon dont fonctionne l'évaluation de la complexité de McCabe.

Fondamentalement, la notation McCabe lit votre code et calcule le nombre de "chemins" uniques qu'il contient. Si vous utilisez McCabe comme numérateur et les lignes de code comme dénominateur, vous obtenez également une assez bonne approximation de la "lisibilité".

Si vous avez 10 lignes de code et que 300 chemins sont traversés par ce code, il s'agit d'un code assez difficile à maintenir (difficile à modifier facilement et en toute sécurité), et il est probablement peu lisible. Inversement, si vous avez 300 lignes de code, mais qu’il n’y a qu’un seul chemin (il n’a pas de conditions), il est à la fois lisible et facilement maintenable.

McCabe tombe cependant dans ce dernier exemple. Si j'ai 300 lignes de code sans conditions, il y a de très bonnes chances que j'ai fait "copier / coller une réutilisation", et ce n'est évidemment pas une bonne chose non plus. Il existe donc des mesures à l'échelle du système que vous appliquez en plus de McCabe - comme la détection de code en double ou presque en double.

Un point que je partagerais est que si le code est construit dans des "modules", et quand je dis cela, je veux dire que vous pouvez changer une chose dans un module et la faire facilement fonctionner avec le tout. Il élimine les effets entre les choses sans rapport. Aussi:

• Le code est facile à réutiliser
• Votre code est flexible (ceci est lié à la construction de modules)
• SEC - Ne te répète pas

Je recommande fortement de lire, le programmeur pragmatique.

Quelques tests / indicateurs:

• Éteignez l'IDE. Pouvez-vous toujours lire votre propre code? Lorsqu'il y a un bogue, est-il assez facile de le parcourir à la main et de déterminer dans quelle classe vous aurez besoin d'un point d'arrêt pour déterminer où se situe le problème? Ou bien, lorsque vous utilisez l'EDI, ne vous inquiétez-vous même pas et passez-vous au premier plan?

• Le débogage devient-il souvent un jeu de wack-a-mole où la correction d'un bogue en crée plus de 2?

• De la détente à quelque chose d’utile, combien d’appels de méthode faut-il? Combien de méthodes transmettent exactement les mêmes ou la plupart des mêmes paramètres à un autre appel de méthode?

• Combien de fichiers devez-vous ouvrir pour ajouter une nouvelle méthode simple à une classe?

• Pensez aux modèles et pratiques que vous avez adoptés. L'avez-vous fait parce que cela avait du sens ou parce que quelqu'un vous a convaincu que "c'est la seule façon de le faire?" ou parce que vous le vouliez sur votre CV ou parce que certains développeurs de rock star l'ont dit.

Comment pourrait-on savoir si le code qu'il a créé est facilement maintenable et lisible?

Vous pouvez repérer du code facile à gérer et lisible en recherchant les propriétés suivantes:

1. Les objets, méthodes et / ou fonctions font toujours une chose.
2. Les méthodes et / ou les fonctions sont concises (comme dans "bref mais complet").
3. Les objets, méthodes et / ou fonctions font essentiellement ce que vous pensez qu'ils sont censés faire en fonction de leurs noms.
4. Le code destiné à être réutilisé est en réalité réutilisable.
5. Dernier point mais non le moindre, si vous pouvez immédiatement tester le code par unité, vous avez probablement au minimum écrit du code modulaire à responsabilité unique.

Comment pourrions-nous savoir si nous avons écrit du code assez désordonné et invraisemblable? Existe-t-il des concepts ou des directives pour savoir si nous avons développé un logiciel compliqué?

1. Si vous lisez une méthode et que l’intention n’est pas claire, c’est au mieux une inélégante et au pire une immuable.
2. Si cela ne semble pas simple, ce n'est probablement pas simple et c'est un signe de code non maintenable ou de code qui deviendra bientôt non maintenable.
3. S'il y a un manque de symétrie (cohérence) dans la base de code, il est probable que vous cherchiez du code non maintenable.

En un mot, Expérience .

Pour commencer, vous devez avoir travaillé sur le terrain. Je ne peux donc pas recommander plus fortement aux programmeurs de prendre le temps de lire des livres tels que Refactoring , qui fourniront certains des outils les plus essentiels de l’arsenal des programmeurs qui s’amélioreront. votre capacité à maintenir le code, et Clean Code, qui a été écrit par certains des talents les plus reconnus dans notre domaine, et décrit presque tout ce que vous devez comprendre pour que votre code soit propre et lisible.

Cependant, aucune quantité de lecture ne remplace l'expérience durement acquise. Vous avez vraiment besoin d’avoir travaillé avec le code pendant un certain temps pour bien apprécier la différence que l’attention apportée à la qualité du code peut faire. En éprouvant le plaisir de travailler avec du code propre et bien factorisé, ainsi que la douleur de travailler avec des spaghettis de code, vous apprendrez à mieux comprendre ce que les auteurs de ces livres essayaient réellement de vous apprendre, mais vous le faites dans un contexte plus large. de code de production réel, dans lequel la qualité de ce que vous faites est importante et influence votre capacité à travailler facilement avec votre code au quotidien.

Il est également utile d’avoir un bon mentor ou un pair expérimenté pour confirmer que vous faites un effort pour écrire du code de qualité. C'est l'une des raisons pour lesquelles les critiques de code peuvent être si utiles. L'utilisation d'outils de vérification du code et de formatage peut également être une aide très utile pour vous assurer de garder les choses propres. Cependant, rien ne se compare à l'expérience acquise au fil des années avec un logiciel d'écriture, si bien que vous vous retrouvez automatiquement à écrire du code propre, lisible et structuré simplement pour en faciliter la maintenance, et tout cela parce que vous avez pris l'habitude d'appliquer les meilleures pratiques pour le faire. longue.

Sans être puritain: préférez le style fonctionnel. De nos jours, la plupart des langues (.NET, Ruby, Python, Javascript, etc.) le prennent en charge et le promeuvent (par exemple, LINQ, underscorejs).

C'est extrêmement facile à lire.

var recentTopCustomers = OrderList
    .Where(o => o.Date >= DateTime.Now.AddDays(-5))
    .Where(o => o.Amount > 1000)
    .OrderBy(o => -o.Amount)
    .Take(10)
    .Select(o => o.Customer);

Cela oblige chaque nœud à avoir une intention unique et ciblée prêtant à la clarté du but. Et parce que chaque tâche discrète est isolée, le saut, le branchement et la réorganisation des nœuds (opérations) à des fins différentes est trivial. Cela facilite la maintenance.

Code lisible et maintenable: code qu’un programmeur, au premier abord, peut comprendre suffisamment pour pouvoir facilement:

• le réutiliser via son interface, ou
• le déboguer, ou
• changer son comportement. (ajouter / supprimer une fonctionnalité), ou
• l'optimiser
• Essaye-le

Cela se résume à la «clarté». C'est-à-dire combien de questions le programmeur doit-il poser à un segment de code particulier avant d'être certain de "bien comprendre ce qu'il fait assez" pour accomplir la tâche en cours sans générer d'effets secondaires inattendus.

Le livre 'Code Complete, de Steve McConnell' est très détaillé.

Il passe en revue diverses mesures que vous pouvez utiliser pour déterminer si le code est de bonne qualité.

Voir un exemple ici: http://books.google.co.uk/books?id=3JfE7TGUwvgC&lpg=PT376&pg=PT389#v=onepage&q&f=false

Minimiser les effets secondaires (idéalement n'en avoir aucun)

Il est beaucoup plus difficile de raisonner et de maintenir une fonction qui provoque 3 changements d’états en dehors de sa propre portée qu’une fonction qui introduit simplement quelque chose et en sort autre chose. Vous ne pouvez pas simplement savoir ce que la fonction fait, vous devez vous rappeler ce qu’elle a fait et comment cela affecte toutes les autres fonctions pertinentes.

Réduire le poids des effets secondaires signifie aussi des classes avec moins de membres, et en particulier moins de membres pouvant modifier l’état de la classe, car les fonctions membres peuvent modifier des états au-delà des leurs et avoir des effets secondaires (elles peuvent manipuler les éléments internes de la classe, par exemple). Cela signifie également que les classes ont moins de données membres propres, de sorte qu'il y a moins d'état de manipulation de ces méthodes et moins d'effets secondaires qu'elles peuvent causer.

Comme exemple simple, imaginons d’essayer de concevoir une structure de données sophistiquée pouvant conserver un sortedétat qu’elle utilise pour déterminer s’il faut effectuer des recherches binaires ou linéaires. Dans un tel cas, il pourrait être utile de séparer le dessin en deux classes. L'appel sortedde la classe non triée peut alors renvoyer une structure de données d'une autre classe qui conserve toujours son contenu trié. Maintenant, vous avez moins d’effets secondaires (donc moins de code source d’erreurs et plus facile à comprendre) ainsi que des codes plus largement applicables (l’ancienne conception gaspillerait à la fois en termes de traitement et d’efficacité intellectuelle pour les petites baies qui n’auraient pas besoin d’être triées).

Évitez les dépendances externes superflues

Vous pourrez peut-être implémenter le code le plus complexe imaginable avec une réutilisation maximale du code en utilisant 13 bibliothèques différentes pour accomplir une tâche relativement simple. Cependant, cela entraîne une surcharge intellectuelle chez vos lecteurs en leur faisant comprendre au moins certaines parties de 13 bibliothèques différentes. Quiconque a essayé de construire et de comprendre une bibliothèque tierce nécessitant l’installation et la construction d’une douzaine d’autres bibliothèques pour pouvoir fonctionner doit immédiatement comprendre cette complexité inhérente.

C'est probablement une vue très controversée, mais je préférerais une duplication de code modeste à l'extrême opposé, à condition que le résultat final soit bien testé (rien de pire que du code défectueux non testé dupliqué à plusieurs reprises). Si vous avez le choix entre 3 lignes de code dupliqué pour calculer un produit vectoriel vectoriel ou en intégrant une bibliothèque mathématique épique uniquement pour réduire 3 lignes de code, je suggérerais le premier, à moins que toute votre équipe ne soit impliquée dans cette bibliothèque mathématique. , à ce stade, vous pouvez toujours envisager d'écrire simplement 3 lignes de code au lieu de 1 si cela est assez trivial en échange des avantages du découplage.

La réutilisation de code est un acte d'équilibre. Si vous en utilisez trop et que vous transférez la complexité intellectuelle de manière un-à-plusieurs, les 3 lignes de code simples que vous avez enregistrées ci-dessus entraînent des coûts qui obligent les lecteurs et les responsables de la maintenance à comprendre plus d'informations que 3 lignes de code. . Cela rend également votre code moins stable, car si la bibliothèque mathématique change, votre code le peut aussi. Si vous en utilisez trop peu et que vous multipliez les coûts intellectuels, votre code cesse de bénéficier d’améliorations centralisées; pour un résultat aussi difficile à maintenir, sinon plus, que l'extrême opposé.

Testez la merde

C’est un acquis, mais si votre code ne gère pas tous les cas de saisie et manque certains cas, comment pouvez-vous espérer que les autres conservent le code que vous avez écrit et que vous n’avez même pas corrigé avant de le transférer aux yeux et aux mains? Il est déjà assez difficile d’apporter des modifications au code qui fonctionne parfaitement, sans parler du code qui n’a jamais été tout à fait correct.

De plus, le code qui passe des tests approfondis trouvera généralement moins de raisons de changer. Cela concerne la stabilité, qui est encore plus difficile à atteindre que la maintenabilité, car un code stable qui ne doit jamais être modifié n’entraîne aucun coût de maintenance.

Documentation d'interface

Si vous ne pouvez pas consacrer autant de temps à documenter les deux, donnez la priorité à "ce que font les choses" et non "à la façon dont les choses fonctionnent". Une interface claire et claire dans ses intentions quant à ce qu’elle fera (ou à tout le moins, ce qu’elle est censée faire) dans tous les cas possibles de saisie donnera un contexte plus clair à sa propre mise en œuvre, ce qui guidera non seulement la d'utiliser le code, mais aussi comment cela fonctionne.

En attendant, le code qui manque de ces qualités là où les gens ne savent même pas ce qu'il est censé faire est SOL, peu importe la précision de ses détails d'implémentation. Un manuel de 20 pages sur la manière dont le code source est implémenté est sans valeur pour les personnes qui ne savent même pas exactement comment il est censé être utilisé et ce qu'il est même supposé faire dans tous les scénarios possibles.

Pour ce qui est de la mise en œuvre, donnez la priorité à la documentation de ce que vous faites différemment des autres. Par exemple, Intel a une hiérarchie de volumes englobante pour ses noyaux de lancer de rayons. Depuis que je travaille dans ce domaine, je peux reconnaître l'essentiel de ce que fait leur code en un coup d'œil sans passer au crible la documentation. Cependant, ils font quelque chose d'unique qui est l'idée de traverser le BVH et d'effectuer des intersections en parallèle en utilisant des paquets de rayons . C'est là que je veux qu'ils hiérarchisent leur documentation, car ces parties du code sont exotiques et inhabituelles de la plupart des implémentations historiques de BVH.

Lisibilité

Cette partie est très subjective. Je ne me soucie pas vraiment de la lisibilité d’un type proche du processus de la pensée humaine. Le code le mieux documenté décrivant les choses au plus haut niveau reste difficile pour moi si l'auteur utilise des processus de pensée bizarres et compliqués pour résoudre un problème. En attendant, un code concis utilisant 2 ou 3 noms de caractères peut souvent être plus facile à comprendre si la logique est très simple. Je suppose que vous pouvez examiner par des pairs et voir ce que les autres préfèrent.

Je m'intéresse surtout à la maintenabilité et, plus important encore, à la stabilité. Le code qui ne trouve aucune raison de changer est un code qui ne nécessite aucun coût de maintenance.

Je dirais qu’une façon de le savoir serait de permettre aux nouveaux membres de l’équipe de prendre le code, de le comprendre et de le modifier pour corriger les défauts / répondre aux nouvelles exigences avec une relative facilité.

Voici une technique que j'aime utiliser:

Montrez le code à l'un de vos programmeurs pairs et demandez-leur de vous expliquer ce qu'il fait. Surveillez ces choses.

1) S'ils ne peuvent pas facilement expliquer le but d'un bloc de code, il le refactorise.
2) S'ils doivent passer à une autre section de code pour comprendre la section actuelle, reformulez-la.
4) Chaque fois que vous ressentez le besoin de parler pendant le processus, cette section de code doit être refactorisée. (Le code ne parle pas pour lui-même).

Le code le plus facile à gérer est le code qui n'y est pas. Ainsi, au lieu d’ajouter au nombre de LOC, un nouveau code qui «réduit» le nombre de LOC (même s’il est légèrement moins maintenable lorsqu’il est visualisé isolément) pourrait rendre la base de code totale plus facile à gérer en réduisant simplement sa taille. Ainsi, la règle principale pour le code maintenable:

• maximiser SEC.

Deuxièmement, la facilité de maintenance n’est pas pire que les dépendances cachées. Donc pour la règle numéro 2:

• Rendre toutes vos dépendances explicites.

Troisièmement, tous les programmeurs ne sont pas aussi compétents pour maintenir ou écrire en utilisant des techniques ou des idiomes spécifiques plus avancés. Détruire toute la base de code vous donnera une grande base de code difficile à maintenir en raison de sa taille. Autoriser les techniques avancées et les expressions dans tout le code fera que tout le code ne peut être maintenu que par les développeurs expérimentés, ce qui est également mauvais. La clé de la maintenabilité est la superposition basée sur le niveau de compétence. Par exemple:

Bibliothèques multi-projets: développeurs seniors, arrière-plans / astuces code / idiome / techniques Bibliothèques spécifiques au projet et système dorsal: développeurs Medior, évitez les éléments les plus avancés et les plus difficiles à expliquer. Les aînés iront dans ce code à la recherche d'opportunités d'amélioration du SEC.

Front-end: développeurs juniors, utilisez un guide de style strict et un ensemble de techniques de construction de langage et de langage à éviter. Les développeurs de Medior vont parcourir ce code à la recherche d'opportunités DRY et d'une logique métier cachée.

Donc pour la règle numéro 3:

• Couchez votre code selon le niveau de compétence du développeur et écrivez le code maintenable en conséquence.

je

Il n’est jamais facile d’écrire du code lisible et facilement maintenable, mais il n’est pas trop difficile d’écrire un code facile à maintenir.

OOAD est un mot de quatre lettres mais difficile à comprendre en une fois - suivez une analyse orientée objet

1. Commencez toujours par un bon cahier des charges et l'exposé exact du problème

   • commencer avec peu de cas d'utilisation, à savoir; Interaction système-utilisateur

2. Vous devez garder vos objets faiblement couplés et vous assurer que votre code ne se répète pas - suivez DRY [ne vous répétez pas]

   • chaque fois que vous voyez un duplicata, recherchez un endroit pour encapsuler
3. votre code est ouvert à l'extension et fermé à la modification - OCP [Principe ouvert-fermé]
4. Lorsque vous modifiez votre code, souvenez-vous toujours - ne créez pas de problèmes pour les résoudre, affirme simplement que le service informatique ne modifie pas les fonctionnalités existantes.
5. Test unitaire de votre code
   • testez toujours votre code lorsque les choses tournent mal
6. Lorsque vous travaillez sur les fonctionnalités, n'oubliez pas de suivre les principes de base de la POO (principes orientés objet) et les techniques pour vous assurer que votre application est bien conçue dès le départ.
   • Les objets doivent faire ce que leur nom indique
   • Chaque objet doit représenter un seul concept
7. Rappelez-vous toujours l'énoncé du problème du système et dans quel logiciel de contexte / domaine fonctionne
8. Faire du papier aussi - ouais ça marche pour moi
   • avoir des impressions de trucs liés à l'interface utilisateur et aux diagrammes UML fonctionnent toujours
   • vous pouvez même avoir les captures d'écran de la session de brainstorming du tableau blanc aussi
9. Mises en page d'architecture
10. Appliquer les principes de conception si possible
11. Documentation
    • toujours documenter votre code
    • définir l'indentation dans l'EDI et documenter cela aussi