Paradigme de développement par le commentaire

J'ai été amené à écrire ce concept par un problème que j'ai rencontré maintes et maintes fois lors d'un nouveau projet: pour 5 ans de développement commercial, j'ai été constamment «chanceux» d'arriver à un projet que le développeur principal quitte. Et chaque fois que j'ai hérité d'une énorme base de code - les lois de son fonctionnement n'étaient comprises que par son créateur. À mon tour, déjà après la première année, j'ai acquis l'habitude du développement par le design et du design par les commentaires. Ce que je veux partager avec vous sous la coupe:

Paradigme de développement par le commentaire

Idée. Conception de commentaire. Code (IC-DC)

Idée: concevoir par des commentaires. Code

• Idée
  L'initiateur de l'idée peut être vous ou une autre personne - par exemple, votre PM (TimLead).

exemple d'une idée: "Vous devez effacer le numéro de téléphone de caractères tels que '+, -, crochets et espaces', de sorte que la sortie ne soit qu'un ensemble de nombres. La fonctionnalité est nécessaire pour implémenter une recherche par numéro de téléphone - saisie de n'importe quelle manière."

• Concevoir par des commentaires
  Rédiger des commentaires décrivant la logique du programme.

exemple de conception à travers des commentaires:

<?php namespace App\Services; use App\Entity\Users; use Doctrine\ORM\EntityManagerInterface; use Doctrine\ORM\EntityManager; class PhoneService { //  ,   //        //    //  ,    8,     7 //   } 

• Écriture de code
  Maintenant, nous devons convertir notre projection de commentaires en code:

exemple:

 <?php namespace App\Services; use App\Entity\Users; use Doctrine\ORM\EntityManagerInterface; use Doctrine\ORM\EntityManager; class PhoneService { //  ,   public function clear_phone(string $phone){ //        $symbols_for_delete = ['+','-','(',')', ' ']; //    $phone = str_replace($symbols_for_delete, '', $phone); //  ,    8,     7 if( $phone[0] == '8' ){ $phone[0] = '7'; } //   return $phone; } } 

À quoi ça sert?

Pourquoi ai-je besoin de commentaires, de code, et donc c'est clair?

Beaucoup diront que le code est le texte - et qu'il est facile à lire. Et je dois mentionner que le code est une méthode pour exprimer vos pensées à travers la syntaxe du langage que vous utilisez. Et lorsque nous écrivons une logique complexe - nous utilisons notre propre style, à bien des égards, unique d'utiliser cette syntaxe. Mais si nous sommes au stade de la conception - nous décrirons notre logique dans un langage généralement accepté, puis en revenant au code après 3 ans, nous comprendrons comment cela fonctionne et notre code. L'héritier pourra tout aussi bien le comprendre. Utiliser la conception par le biais de commentaires - réduit l'entropie de votre projet et rend le code plus beau.

Pourquoi ai-je besoin de design, puis-je m'asseoir et tout écrire en même temps?

Si vous posez cette question, il vous suffit de lire d'urgence le " Code parfait " de Steve McConnell . Là, ce concept est plus que divulgué.
Je vais donner une petite citation:

Au stade de la conception du code, 75% des erreurs sont généralement détectées. S'ils n'étaient pas trouvés, je devrais refactoriser.

En effet, au stade de la conception, vous pouvez comprendre que la logique métier conçue ne fonctionnera pas comme prévu, ou vous pouvez voir une meilleure approche pour résoudre un problème particulier. Et vous n'aurez pas besoin de revenir plus tard et de remanier un morceau de logique - qui ne fonctionne pas exactement comme prévu.

Dois-je commenter tout?

J'ai donné des exemples élémentaires ci-dessus. Ils sont parfaitement compréhensibles et sans commentaires, mais j'ai quand même utilisé l'approche IC-DC pour les mettre en œuvre. Parce que Je ne veux pas que mon code augmente l'entropie. J'ai visité de nombreux projets où la plupart des projets ont dû être réécrits à partir de zéro précisément en raison de l'énorme entropie en eux. Réfléchissez si vous voulez que le projet qui a passé des mois ou des années de votre vie soit simplement effacé. Si la réponse est non, je pense qu'il vaut toujours la peine d'utiliser cette approche. Parce que si vous quittez le projet ou quelques années plus tard, une nouvelle technologie apparaît qui peut mieux répondre aux besoins que votre ancienne solution - IC-DC vous aidera à mettre en œuvre les changements de manière optimale, en atteignant le minimum de fonctionnalités, car un nouvel employé ou un nouveau comprendra comment et pourquoi cela fonctionne.