Ce billet fait partie d'une série en 4 volets : #1, #2, #3, #4.
Suite de ma sélection de citations et de notes sur le livre Software engineering at Google.
Cette partie rassemble mes notes sur les pratiques de génie logiciel.
Guides de style et règles
Chap. 8 Style guides and rules
Un ensemble de guides de style définit les règles chez Google. Les règles sont des lois. Elles sont strictes et obligatoires pour les développeurs.
Un guide de style permet de se concentrer sur ce que le code doit dire plutôt que sur la façon dont il le dit.
Il offre des gains de cohérence et de réduction des conflits pour 30.000+ ingénieurs et environ 60.000 soumissions faites chaque jour dans une base de code de plus de 2 milliards de lignes de code.
Principes d'un guide de style :
- optimiser le code pour le lecteur, "no clever code"
- être consistant (similitude, conformité, uniformité), pour être capable de passer d'un projet ou d'une équipe à l'autre et être immédiatement productif
- éviter les constructions surprenantes ou pouvant être source d'erreurs, les "power features" d'un langage peuvent causer des problèmes, c'est mieux de ne pas les utiliser
- favoriser les aspects pratiques quand c'est nécessaire
- documenter le raisonnement derrière une règle permet de reconnaître quand les choses doivent changer
Les commentaires :
- de documentation (ceux en en-tête d'un fichier, d'une classe ou d'une fonction) décrivent le design ou l'intention du code qui suit
- d'implémentation (ceux dans le code lui-même) justifient ou soulignent les choix non évidents, expliquent les passages délicats et les parties importantes du code
Même si un code est bien compris par les ingénieurs d'un projet, il n'est pas garanti que les futurs mainteneurs aient la même compréhension. Google accorde une grande importance à la simplicité du code, quand c'est plus facile à comprendre, c'est plus facile à maintenir.
Il y a une différence entre avoir la connaissance d'un langage et savoir comment ce langage est utilisé au sein de Google. Les cours "
Automatiser l'application des règles quand c'est possible.
Revue de code
Chap. 9 Code Review
Just Do It, Steve McConnell donne de nombreuses raisons de l'efficacité des revues de code dans Code Complete.
Google a un outil interne nommé Critique. Un développeur fait d'abord son auto-revue en inspectant les commentaires automatiques de l'outil. Ensuite, un seul LGTM est suffisant pour fusionner un changement.
Trois éléments nécessitent une "approbation" dans une revue de code chez Google :
- justesse et compréhension du code (le code doit faire ce que l'auteur prétend qu'il fait)
- justesse du code par l'un des "propriétaires" de cette partie du code (un CODEOWNER)
- "lisibilité" du langage utilisé
Dans la plupart des cas, une seule personne assume les trois rôles. L'auteur peut également assumer les deux derniers rôles et n'avoir besoin que d'un LGTM d'une autre personne.
Une procédure de revue de code bien conçue et une culture de prise au sérieux des revues a les avantages suivants :
- assurer la justesse du code
- assurer la compréhension du code par les autres développeurs
- assurer la cohérence entre les différentes bases de code
- faire en sorte que le code appartienne à l'équipe plutôt qu'à une personne
- partager les connaissances
- avoir un historique de révision du code
Ces points sont essentiels pour toute organisation de programmation informatique qui dure dans le temps. Ils sont bénéfiques pour l'auteur du code mais aussi pour ceux qui font la revue.
L'étape de compréhension du code permet d'avoir un retour avec une autre perspective que celle de l'auteur. Elle permet de voir si un public plus large est capable de comprendre les modifications. Il faut tenter d'adopter la posture suivante : "le relecteur a toujours raison". Les questions de compréhension qui arrivent maintenant seront multipliées par deux au fil du temps.
La certification de "lisibilité" d'un langage est accordée aux personnes qui suivent une formation interne chez Google. Ils peuvent préférer un code moins complexe qui n'est peut-être pas le "meilleur" sur le plan fonctionnel, mais qui est plus facile à comprendre.
La revue de code rappelle aux développeurs que le code n'est pas "le leur" mais celui de l'équipe. Sans revue de code, la plupart des développeurs graviteraient naturellement vers un style personnel et leur propre approche de la conception de logiciels.
C'est humain d'être fier de son métier et d'être réticent à soumettre son code à la critique. La revue de code permet d'atténuer ce qui pourrait être une interaction chargée d'émotion. Quand elle fonctionne bien, elle permet non seulement de remettre en question les hypothèses des développeurs, mais aussi de le faire de manière neutre.
La plupart des développeurs ne sont pas des perfectionnistes et viseront un code qui "fait le travail" plutôt qu'un code parfait mais plus long à produire. Sans revue de code, beaucoup d'entre nous prendraient des raccourcis : "je n'ai pas fait tous les tests unitaires, mais je le ferai plus tard". La revue de code oblige un développeur à corriger ces problèmes avant d'envoyer la modification.
Bonnes pratiques en revue de code :
- soyez poli et professionnel : il vaut mieux poser des questions sur les raisons pour lesquelles une chose a été faite de telle manière avant de supposer que c'est une mauvaise approche. N'oubliez pas que vous n'êtes pas votre code et que le changement que vous proposez n'est pas "le vôtre" mais celui de l'équipe
- Google s'attend à ce qu'une revue de code soit terminée dans les 24 heures
- limitez la taille de vos changements : les examinateurs peuvent rejeter des changements trop importants pour une seule revue (Google recommande 200 lignes de code)
- rédigez une bonne description des changements que vous apportez
- affectez le nombre minimum possible d'examinateurs
- automatisez partout où c'est possible (analyse statique, pre-commit hooks etc.)
Types de revues de code :
- nouveau code (greenfield reviews) et nouvelles fonctionnalités
- changements de comportement, améliorations et optimisation de code existant
- corrections de bugs et rollbacks
- refactoring et changements à grande échelle
Ce changement est-il nécessaire et est-ce que ce changement améliore la base de code ?
Documentation
Chap. 10 Documentation
La documentation ne donne aucun avantage immédiat à l'auteur, son coût est amorti sur le long terme. C'est peut-être une des raisons pour laquelle il est parfois difficile d'obtenir des gens qu'ils l'écrivent.
La documentation permet d'éclaircir les questions relatives aux décisions prises en matière de conception et d'implémentation.
Il y a beaucoup de similitudes entre l'écriture de documentation et l'écriture de code. Comme avec un langage de programmation, il y a des règles, une syntaxe particulière et des décisions de style, souvent pour atteindre un objectif similaire à celui du code : renforcer la cohérence, améliorer la clarté et éviter les erreurs de compréhension.
Certains ingénieurs chez Google aimeraient tendre vers une documentation vue comme du code. Voir Docs as Code :
Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code.
Les points suivants devraient être abordés dans les premiers paragraphes d'une documentation technique :
- à qui s'adresse cette documentation ?
- quel est son but ?
- quand a-t-elle été créé ?
- où ce document doit-il se trouver ?
- pourquoi ce document a-t-il été créé ?
- que doit pouvoir faire le lecteur après l'avoir lu ?
C'est dans ce chapitre sur la documentation qu'on trouve la citation attribuée à Pascal Blaise :
"If I had more time, I would have written you a shorter letter".
La plupart des équipes de Google exigent un document de conception (design doc) approuvé avant de commencer à travailler sur un projet important. Il est souvent partagé dans Google Docs qui dispose d'outils de collaboration. Certaines équipes exigent que ces documents soient discutés et débattus lors de réunions d'équipe spécifiques.
Un bon document de conception doit montrer les objectifs du design et la stratégie de sa mise en œuvre. Il doit proposer des décisions clés en mettant l'accent sur les compromis. Les meilleurs documents suggèrent des alternatives de design, en indiquant les points forts et les points faibles de chaque possibilité.
Joint