Bonjour, Habr!
Combien de fois aviez-vous que vous ou vos collègues ne pouviez pas décrire votre propre code avec quelques phrases?
J'attire votre attention sur une traduction de l'article «Comment écrire du code facilement descriptible» de Cedd Burge , dans lequel il partage ses conseils sur la façon d'éviter de telles situations.
Lorsque le code est difficile à décrire avec des mots, la plupart des gens doivent faire preuve d'imagination pour ce faire. Pour cette raison, l'énergie mentale est gaspillée et le risque d'erreurs dans l'interprétation du code est accru. Différentes personnes percevront toujours les mots à leur manière, ce qui créera de la confusion lors de la discussion du code.
En règle générale, ces discussions deviennent un terrain fertile pour les erreurs qui apparaissent en raison de malentendus, et la correction de ces erreurs conduit souvent à l'apparition de nouvelles erreurs pour les mêmes raisons. En fin de compte, nous obtenons un code incompréhensible avec lequel personne ne veut travailler.
Exemple de code indescriptible
Vous pourriez penser que le code n'est qu'un langage écrit. Si le code semble simple, il peut être facilement lu, décrit et compris. Mais ce n'est pas toujours le cas.
La décision générale ci-dessous détermine si une année est une année bissextile.
(divisibleBy(4) and not divisibleBy(100)) or divisibleBy(400)
Il s'agit d'un code simple. Il appelle des fonctions 3 fois, possède 3 opérateurs (et, ou, non) et deux niveaux d'imbrication.
Mais je pense que si on vous donne une seconde pour décrire cet algorithme en utilisant des mots, vous aurez du mal.
Peut-être «une année est une année bissextile si elle est divisible par 4 et non divisible par 100, ou divisible par 400»?
Le problème est qu'en mots, contrairement au code, il n'y a pas de crochets. Par conséquent, il est difficile de décrire adéquatement la condition avec des mots et si le mot "est divisible par 400" se réfère à "divisible par 4" ou "non divisible par 400". Pour contourner ce problème, vous pouvez spécifier des parenthèses avec votre main ou prendre des pauses plus longues entre les conditions, mais la probabilité d'une erreur restera grande.
Refactorisation du code décrit
Nous pouvons d'abord décrire les conditions avec des mots et ensuite seulement les réduire, en les rendant aussi claires et concises que possible. Commençons comme ceci:
"400 ans est un cas unique. Si une année est divisible par 400, alors c'est une année bissextile. 100 ans est également un cas unique. Si une année est divisible par 100, alors ce n'est pas une année bissextile à moins qu'elle ne soit divisible par 400, donc la priorité pour le cas spécial est «400 ans». S'il n'y a pas de cas spécial, alors cette année est une année bissextile, à condition qu'elle soit divisée par 4 ».
Cela semble clair, mais pas concis, nous allons donc raccourcir un peu le texte:
«Si l'année est divisée par 400, alors c'est une année bissextile. Si elle est divisée par 100, alors c'est une année normale, mais lorsqu'elle est divisée par 4, c'est une année bissextile. "
Si nous transformons ces mots en code, nous obtenons quelque chose comme ceci:
if divisbleBy(400): return LeapYear elif divisbleBy(100) return NormalYear elif divisbleBy(4): return LeapYear else: return NormalYear
Conclusions
Le code difficile à comprendre est monnaie courante pour presque tous les programmeurs. Nous nous aiderons nous-mêmes et nos collègues si nous écrivons du code facilement décrit par des mots.
Et surtout, écrire du code de cette manière est plus facile, car il n'y a pas de vain effort mental. L'astuce est que l'algorithme est d'abord décrit par les mots qui seront ensuite utilisés pour écrire le code.
Dans de nombreuses organisations, le code a déjà commencé à être décrit en mots dans des tests d'acceptation ou des user stories, ce qui peut améliorer la productivité.