Il n'y a que deux choses difficiles en informatique: l'invalidation du cache
et nommer les choses.
- Phil Karlton
Nous, développeurs, passons plus de temps à lire du code qu'à l'écrire. Il est important que le code soit lisible et clair sur son intention.
Voici quelques conseils basés sur mon expérience en nommant les choses.
Signification
Un nom, que ce soit une variable, une propriété, une classe ou une interface, doit refléter le but de son introduction et son utilisation.
Utilisez des noms précis
Si l'on ne peut se faire une idée de l'utilisation et du but sans commentaires supplémentaires, le nom n'est pas assez bon. Si une utilisation immédiate ou une idée de finalité basée sur la dénomination est incorrecte, la dénomination est inacceptable.
La pire dénomination possible est lorsqu'un nom de méthode appartient à celui qui le lit.
Évitez les noms dénués de sens
Ce sont des noms comme $i , $j , $k etc. Bien que ceux-ci soient OK à utiliser dans les cycles, dans d'autres cas, ils gaspillent la lisibilité.
Une source courante de ces noms est la science classique où la plupart des formules utilisent des variables à une lettre, ce qui accélère l'écriture. Par conséquent, vous ne pouvez pas comprendre ces formules sans un paragraphe d'introduction expliquant la dénomination. Souvent, ce paragraphe est difficile à trouver.
Étant donné que l'enseignement de l'informatique comprend un nombre important de disciplines scientifiques classiques, les étudiants s'habituent à ce nom et l'appliquent à la programmation.
Nommer des classes, des interfaces, des propriétés et des méthodes
Le nom de classe doit être un ou plusieurs noms. Il ne devrait pas y avoir de verbes. Essayez d'éviter les "données", "gestionnaire", "info", "processeur", "gestionnaire", "fabricant", "util" etc. car ceux-ci sont généralement un indicateur de dénomination vague.
Les interfaces sont généralement des noms ou des adjectifs. Certaines équipes, dont PHP-FIG , ont choisi de postfixer les interfaces avec Interface . Certains le font avec le préfixe I et certains n'utilisent aucun préfixe ou postfix. Je trouve tout cela acceptable au cas où vous seriez cohérent.
Les propriétés doivent être nommées avec des noms ou des adjectifs. Pour les booléens, utilisez des phrases affirmatives préfixées par "Is", "Can" ou "Has", le cas échéant.
Les noms de méthode doivent contenir un ou plusieurs verbes car ce sont des actions. Choisissez un verbe qui décrit ce que fait la méthode, pas comment elle le fait.
Bien que cela ne soit pas strictement nécessaire, c'est une bonne idée de terminer le nom de classe dérivée par le nom de la classe de base:
class Exception {} class InvalidArgumentException extends Exception {}
Cohérence
Utilisez un seul nom pour un seul concept. Soyez cohérent.
Un bon exemple est d'utiliser begin / end partout au lieu de le mélanger avec start / finish .
Suivez les conventions de style de code
Lors du développement d'un projet, une équipe doit convenir du style de code et des conventions de dénomination qu'elle utilise et les respecter. Si une partie des conventions n'est pas acceptée par certains membres de l'équipe, elle doit être revue, modifiée et une nouvelle règle doit être définie.
Pour PHP, la convention la plus courante est actuellement PSR-2 et la plupart des conventions de projet internes sont basées sur elle.
Verbosité
Évitez de réutiliser des noms
L'utilisation du même nom pour de nombreux concepts doit être évitée si possible car cela pose deux problèmes:
- Lors de la lecture, vous devez garder le contexte à l'esprit. Cela signifie généralement accéder constamment à l'espace de noms ou à la déclaration de package.
- La recherche de tels noms est pénible.
Évitez les contractions
N'utilisez pas de contractions. Des exemples courants sont:
function cntBigWrds($data, $length) { $i = 0; foreach ($data as $iter) { if (mb_strlen($iter) > $length) { $i++; } } return $i; } $data = ['I', 'am', 'word']; echo cntBigWrds($data, 3);
Le code ci-dessus, lorsqu'il est nommé correctement, devient:
function countWordsLongerThan(array $words, int $minimumLength) { $count = 0; foreach ($words as $word) { if (mb_strlen($word) > $minimumLength) { $count++; } } return $count; } $words = ['I', 'am', 'word']; echo countWordsLongerThan($words, 3);
Notez encore que les noms explicatifs courts sans contractions sont meilleurs que les noms explicatifs longs, donc ne prenez pas la verbosité à l'extrême avec des noms comme processTextReplacingMoreThanASingleSpaceWithASingleSpace() .
Si le nom est trop long, cela signifie qu'il pourrait être reformulé pour le raccourcir ou que la chose que vous nommez en fait trop et devrait être refactorisée en plusieurs choses.
Évitez les acronymes
Évitez les acronymes et les abréviations, à l'exception de ceux connus comme le HTML. Elon Musk a envoyé un e-mail intitulé "Acronymes serieusement sucer" à tous les employés de SpaceX en mai 2010:
Il y a une tendance rampante à utiliser des acronymes inventés chez SpaceX. L'utilisation excessive d'acronymes inventés est un obstacle important à la communication et le maintien d'une bonne communication à mesure que nous grandissons est extrêmement important. Individuellement, quelques acronymes ici et là peuvent ne pas sembler si mauvais, mais si un millier de personnes les inventent, avec le temps, le résultat sera un énorme glossaire que nous devrons remettre aux nouveaux employés. Personne ne peut se souvenir de tous ces acronymes et les gens ne veulent pas sembler stupides lors d'une réunion, alors ils restent assis là dans l'ignorance. Cela est particulièrement difficile pour les nouveaux employés.
Cela doit cesser immédiatement ou je prendrai des mesures drastiques - j'ai donné suffisamment d'avertissement au fil des ans. À moins qu'un acronyme ne soit approuvé par moi, il ne doit pas entrer dans le glossaire SpaceX. S'il existe un acronyme qui ne peut être raisonnablement justifié, il doit être éliminé, comme je l'ai demandé par le passé.
Par exemple, il ne devrait pas y avoir de désignation «HTS» [banc d'essai horizontal] ou «VTS» [banc d'essai vertical] pour les bancs d'essai. Celles-ci sont particulièrement stupides, car elles contiennent des mots inutiles. Un «stand» sur notre site de test est évidemment un banc de test. VTS-3 est quatre syllabes par rapport à "Tripod", qui est deux, donc la version acronyme sanglante prend en fait plus de temps à dire que le nom!
Le test clé pour un acronyme consiste à se demander s'il aide ou nuit à la communication. Un acronyme que la plupart des ingénieurs en dehors de SpaceX connaissent déjà, comme GUI, est très bien utilisé. Il est également correct de créer quelques acronymes / contractions de temps en temps, en supposant que je les ai approuvés, par exemple MVac et M9 au lieu de Merlin 1C-Vacuum ou Merlin 1C-Sea Level, mais ceux-ci doivent être réduits au minimum.
Je suis d'accord avec lui.
Lisibilité
Le code doit pouvoir être lu aussi facilement que la prose. Choisissez des mots que vous choisiriez d'écrire un article ou un livre. Par exemple, une propriété nommée TotalAmount est plus lisible en anglais que AmountTotal .
Masquage des détails d'implémentation
Cela concerne davantage la conception orientée objet, mais cela affecte beaucoup la lisibilité si les détails de l'implémentation sont exposés. Essayez de ne pas exposer les méthodes nommées comme:
initializeinitcreatebuild
Langue du domaine
Le code doit utiliser les mêmes noms que ceux utilisés dans le modèle d'entreprise ou de domaine automatisé.
Par exemple, si une entreprise de voyages utilise "lieu" comme nom général pour les cafés, les hôtels et les attractions touristiques, ce n'est pas une bonne idée d'utiliser "lieu" dans le code parce que vous et vos utilisateurs parlerez deux langues différentes, ce qui compliquera les choses. qu'il ne le devrait.
Un tel langage est souvent appelé "The Ubiquitous Language". Vous pouvez en savoir plus sur le mini-livre « Domain Driven Design Quickly » d'InfoQ.
Anglais
La majorité des langages de programmation utilisent l'anglais pour les constructions intégrées et c'est une bonne pratique de nommer les choses en anglais également. Il est extrêmement important pour un développeur d'apprendre l'anglais au moins au niveau de base et, ce qui est plus important, d'avoir un bon vocabulaire que l'on peut utiliser pour trouver un bon nom.
Quelques outils utiles:
Les références