Je pense qu'il y a en fait deux points à traiter et je les examinerais en fait séparément car ils ne peuvent pas être abordés de la même manière, même si je les trouve importants.
- L'aspect technique: qui vise à éviter le code risqué ou mal formé (même si accepté par le compilateur / interprète)
- L'aspect présentation: qui consiste à rendre le programme clair pour les lecteurs
L'aspect technique que je qualifie de norme de codage , tout comme Herb Sutter et Andrei Alexandrescu avec leurs normes de codage C ++ . La présentation que je qualifie de style de codage , qui inclut la convention de nommage, l’indentation, etc.
Norme de codage
Parce qu’elle est purement technique, une norme de codage peut être principalement objective. En tant que telle, chaque règle devrait être étayée par une raison. Dans le livre que j'ai référé à chaque article a:
- Un titre simple et pertinent
- Un résumé qui explique le titre
- Une discussion, qui illustre la question de faire autrement et énonce donc la raison
- optionnel Quelques exemples, car un bon exemple vaut mille mots
- optionnel Liste d'exceptions pour lesquelles cette règle ne peut pas être appliquée, parfois avec des solutions de contournement.
- Une liste de références (autres livres, sites Web) ayant traité ce point
La justification et les exceptions sont très importantes car elles résument le pourquoi et le moment.
Le titre doit être suffisamment explicite pour que lors des examens, il ne soit nécessaire que de disposer d’une liste de titres (aide-mémoire) avec laquelle travailler. Et évidemment, regroupez les articles par catégorie pour faciliter leur recherche.
Sutter et Alexandrescu ont réussi à avoir une liste de cent éléments seulement, même si C ++ est réputé poilu;)
Style de codage
Cette partie est généralement moins objective (et peut être carrément subjective). Le but ici est de garantir la cohérence, car cela aide les mainteneurs et les nouveaux venus.
Vous ne voulez pas entrer dans une guerre sainte sur le style d'indentation ou d'accolade qui convient le mieux ici, il existe des forums dans ce sens: ainsi dans cette catégorie, vous faites les choses par consensus> vote à la majorité> décision arbitraire du ou des dirigeants.
Pour un exemple de formatage, voir la liste des options de Style artistique . Idéalement, les règles devraient être suffisamment claires et complètes pour qu'un programme puisse réécrire le code (même s'il est peu probable que vous en codiez un un;))
Pour la convention de dénomination, j'essaierais de distinguer facilement les classes / types des variables / attributs.
C’est aussi dans cette catégorie que je classe les "mesures" comme:
- préférez les méthodes courtes aux méthodes longues: il est généralement difficile de s’entendre sur la durée
- Préférez le retour / continuer / pause plus tôt pour réduire le retrait
Misc?
Enfin, un élément est rarement, sinon jamais, abordé dans les normes de codage, peut-être parce qu’il est propre à chaque application: l’organisation du code. La question architecturale est peut-être la question la plus en suspens, bousiller la conception initiale et vous en souffrirez dans des années. Vous devriez peut-être ajouter une section pour la gestion de fichiers de base: en-têtes publics / privés, gestion des dépendances, séparation des activités, interface avec d'autres systèmes ou bibliothèques ...
Mais ce ne sont rien si elles ne sont pas réellement appliquées et appliquées .
Toute violation doit être signalée lors de la révision du code, et aucune révision du code ne devrait être acceptable si une violation est en cours:
- corriger le code pour correspondre à la règle
- corrige la règle pour que le code ne ressorte plus
Évidemment, changer une règle signifie obtenir le feu vert des dirigeants.