Que devrait être dans une norme de codage? [fermé]

Qu'est-ce qui devrait figurer dans une bonne norme de codage (lire: utile)?

• Les choses que le code devrait avoir.
• Des choses que le code ne devrait pas avoir.
• La norme de codage devrait-elle inclure des définitions d'éléments que le langage, le compilateur ou le formateur de code impose?
• Qu'en est-il des mesures telles que la complexité cyclomatique, les lignes par fichier, etc.?

Une raison pour chaque exigence. De cette façon, suivre la norme ne devient pas une sorte de culte du fret et les gens savent qu'il est correct de changer de norme si la raison de cette décision ne s'applique plus ou de ne pas respecter la norme dans des cas spécifiques où la raison ne s'applique clairement pas. .

Onglets vs espaces! Je reçois des mises à jour folles lorsqu'un de mes collègues a accidentellement validé beaucoup d'onglets pour déplacer les espaces dans le référentiel

Conventions de nommage

EDIT: J'entends par cela les directives de nommage, pas les règles de nommage.

Par exemple, une ligne directrice serait All boolean values should begin with Is/Can/Has/etc when possible. Une règle seraitAll boolean values must start with Is

Une norme de codage pour un groupe devrait inclure les options du compilateur pour les avertissements et les erreurs à traiter.

Les programmeurs devraient être libres d' augmenter les avertissements pour leur propre code, mais il doit exister une base de référence afin que la lecture et l'utilisation du code de quelqu'un d'autre n'encombrent pas la sortie du compilateur.

Une telle norme devrait également indiquer comment les programmeurs peuvent désactiver de tels avertissements au cas par cas, s’il existe un élément de code exceptionnel qui, sinon, ne serait pas conforme.

Certaines normes que j'aime bien (je sais qu'il y en a beaucoup, mais ce sont celles que je préfère):

• Couverture à 80% des tests unitaires
• Propriété collective du code (écrivez le code à lire par vos coéquipiers, pas par le compilateur)
• Ecrire des commentaires. Ecrivez ce que vous diriez à un nouveau venu.
• Rester simple

Les normes de codage aident un peu lorsque vous écrivez le code pour la première fois, elles aident beaucoup lorsque vous, ou votre remplaçant, devez mettre à jour le code 2 ans plus tard.

La norme idéale mène au code où vous pouvez accéder à n'importe quelle page du code et comprendre exactement ce qu'il fait lors de la première lecture, car

• les noms décrivent clairement les données manipulées,
• les accolades rendent le flux de contrôle clair,
• les commentaires expliquent tout algorithme non évident, etc.

D'autre part, trop de normes arbitraires peuvent perturber le flux d'écriture de code. Je pense donc que chaque élément d'une convention de codage proposée devrait être évalué en fonction de ces 2 critères:

• Cette règle aide-t-elle à garantir que le code est correct ?
• Cette règle aide-t-elle à garantir que le code est clair ?

Si ni l'une ni l'autre n'est vraie, l'élément est simplement arbitraire et probablement inutile

Je voudrais inclure les éléments suivants dans une norme que j'écris:

Pour plus de clarté:

• Organisation du fichier: La définition d'un ordre fixe pour les éléments d'un fichier permet à l'équipe de naviguer facilement dans les autres fichiers. Vous ne devriez pas avoir à chercher pour trouver #defines, ou des définitions de structure.

• Conventions de dénomination: une dénomination cohérente facilite la lisibilité. Mais évitez de spécifier trop de règles, cela nuit à l'écriture.

• Structure du code. Emplacement des accolades, niveaux d'indentation, espaces par rapport aux tabulations, etc. Oui, cela peut constituer une préférence personnelle forte, mais l'objectif est un code clair. Trouvez la meilleure option pour l’équipe et persévérez.

Pour la correction:

• Meilleures pratiques spécifiques à votre type de problème: Règles relatives à l'allocation de mémoire, à la concurrence ou à la portabilité.

• "Const Correctness", utilisation appropriée de staticet volatile, etc.

• Règles relatives aux macros du préprocesseur et autres fonctionnalités du langage facilement utilisables.

Idées inspirantes et pragmatiques qui font réfléchir les gens, plutôt que des restrictions négatives qui empêchent les gens de penser.

Sinon, vous obtenez des singes de code qui ont peur d'aller après les bananes .

Que devrait être dans une norme de codage? Aussi petit que possible. Moins plutôt plus. Et avec justification, s'il vous plaît.

Non pas parce que je suis un codeur cow-boy qui ne veut aucun processus, mais parce que j'ai vu de lourdes spécifications de codage sans aucune logique derrière (probablement), "j'ai trouvé ceci sur le" Net quelque part en 95 "qui finit par devenir un cauchemar bureaucratique pour travailler avec.

Certaines personnes semblent sincèrement croire qu’en augmentant les normes, elles verront une augmentation correspondante de la "qualité" du code et qu’elles le feront peut-être aussi. En attendant, ils vont ignorer l'architecture, les performances, le bon sens et bien d'autres choses qui importent plus que le nombre de lignes d'un fichier.

Une procédure de révision du code pour appliquer la norme. Oh, et trouver des insectes aussi.

Un bon vieux bon sens ne voudrait pas aller mal; il y a beaucoup trop de documents standard de codage que de travailler sur des points non pertinents (des éléments tels que le type et la taille de police sont l'un des plus extrêmes que j'ai vus).

La meilleure chose à faire si vous faites partie d’un groupe de développeurs est de discuter entre vous et de regarder votre code, de vous mettre d’accord sur ce qui est acceptable et si vous devez écrire les points principaux sous forme de directives, mais conservez-les comme suit. juste que des directives. Si vous ne pouvez justifier aucune divergence par rapport aux directives, vous devriez vraiment vous demander pourquoi vous le faites.

En fin de compte, un code clair et compréhensible est plus important que toute règle rigide en matière de mise en page ou de typographie.

Comme d'autres l'ont mentionné, la couverture de test de code est importante. J'aime aussi voir:

• Structure du projet. Les tests font-ils partie du code ou sont-ils dans un répertoire project / package / séparé? Le code de l'interface utilisateur est-il compatible avec les éléments du back-end? Si non, comment est-il compartimenté?

• Processus de développement. Écrire des tests avant le code? Est-ce que la réparation des builds cassés a la priorité sur le développement? Quand les révisions de code sont-elles effectuées et que doivent-elles couvrir?

• Gestion du code source. Qu'est-ce qui est vérifié quand? Les documents de conception et les plans de test sont-ils contrôlés par la révision? Quand branchez-vous et quand étiquetez-vous? Conservez-vous les versions précédentes, et si oui combien / pour combien de temps?

• Normes de déploiement. Comment une version est-elle packagée? Que faut-il inclure dans les notes de publication? Comment les scripts de mise à niveau sont-ils créés / contrôlés / exécutés?

Oubliez toutes ces conneries sur les conventions de nommage, le formatage et le nombre de lignes pouvant être contenues dans une fonction / méthode / module. Une règle: utilisez quel que soit le style existant dans tout ce que vous éditez. Si vous n'aimez pas le style de quelqu'un, choisissez-le dans une révision du code. La seule exception à cette règle pourrait être le problème tabs-vs-spaces, ne serait-ce que parce que de nombreux éditeurs / IDE convertiront aveuglément les uns aux autres, et vous finirez par détruire l'historique de vos modifications car chaque ligne a été modifiée.

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.

J'aime le format dans les directives de conception du cadre, il comprend une section générale et des explications pour les directives. Les éléments les plus utiles sont les détails qui commencent par Do, Do Not, Avoid and Consider.

Voici un exemple dans la section Implémentation explicite de membres d'interface, qui contient les éléments suivants (remarque: j'ai supprimé les justifications pour le bien de Bervity)

Éviter implémenter explicitement les membres de l'interface sans avoir une raison forte de le faire

Considérer implémenter explicitement les membres d'interface si ceux-ci ne doivent être appelés que via l'interface.

Ne pas membres explicites comme limite de sécurité.

Faire fournir un membre virtuel protégé qui offre les mêmes fonctionnalités que le> membre explicitement mis en œuvre si la fonctionnalité est destinée à être spécialisés par des classes dérivées.

Cela crée un bon ton général. En utilisant Avoid and Consider, vous pouvez autoriser les développeurs à utiliser leur jugement. En outre, étant donné qu’il s’agit de directives et non de règles, les développeurs sont susceptibles de les trouver plus acceptables et donc plus susceptibles de les suivre.

Personne ne semble avoir parlé de sécurité - dans une norme de codage, vous devez faire référence aux exigences de sécurité (par exemple, utilisation de modules de validation des entrées, interdiction des fonctions faibles connues telles que la commande strcpy, la gestion des erreurs, etc.).

Exemples. Des exemples bien ordonnés, non triviaux, proches du monde réel, qui utilisent chaque règle. Commentaires (ne faisant pas nécessairement partie du code) quelle partie de l'exemple suit quelle règle.

Modèles. Pas le genre C ++, mais quelque chose à copier-coller et remplir avec live. Il est beaucoup plus facile d’obtenir ce commentaire passe-partout de 24 lignes lorsque vous avez une référence à copier.

Caractéristique numéro un: Un maximum absolu de deux pages.

C’est quelque chose que tous les développeurs doivent lire et mémoriser. Vous ne devriez pas avoir à chercher dans la norme à chaque fois que vous devez écrire une nouvelle fonction (ou pire, une nouvelle ligne). Alors, soyez bref et ne gardez que les règles qui fournissent réellement une valeur accrue au produit final.

Les normes de codage sont vraiment plusieurs éléments:

Conventions de codage

• ces choses n'ont pas besoin d'une raison autre que "la cohérence de la base de code" par exemple. utiliser '_' dans les variables membres privées ou non.
• il pourrait y avoir plusieurs approches correctes. Juste besoin d'en choisir un pour la cohérence. par ex. traitement des erreurs à l'aide d'exceptions ou de codes d'erreur.

Les meilleures pratiques

• ces articles ont toujours besoin d'une bonne raison avec quelques exemples clairs

par ex. Ne jamais laisser vide Catch après essai

try { Foo(); } catch { //do nothing }

1) Si une exception est générée par Foo (), d'autres fonctions peuvent suivre sur les fonctions suivantes, ce qui suppose que foo a réussi.

2) Le gestionnaire d'erreurs global ne notifiera pas l'équipe de support de l'exception quand cela se produit sur prod

• couvre les pratiques de "codage défensif", comme l'utilisation d'assertions pour tester vos hypothèses.

Environnement de codage

• des outils que toute l'équipe utilise. par ex. VS 2010, Resharper, Four, etc.

Les normes de codage, quand elles sont écrites sur papier, n’ont que peu d’efficacité. J'aime comment Go publie sa norme de codage. Il a l'outil gofmtpour formater le texte du programme en un format. Tout débat sur le format de codage aboutira alors simplement à un correctif des sources degofmt .

Quant à ce que le format devrait avoir,

• comment nommer des variables, des macros, des constantes, des littéraux, des fonctions, etc.
• comment placer {,}, (,), [,] en ce qui concerne le ifcorps de la fonction, les blocs d'instructions à d'autres fins,
• quelle est la largeur des empreintes,
• combien de caractères une ligne de texte est autorisée
• combien de niveaux d'indentation sont autorisés avant que le code soit rejeté / envoyé pour refactoring
• combien de lignes de code sont autorisées par fonction avant qu'il ne soit renvoyé pour refactoring
• nombre maximum d'arguments qu'une fonction peut prendre avant d'être renvoyée pour refactoring
• Quelques lignes de commentaires avant qu'une fonction commence commence à expliquer brièvement ce qu'elle fait, si le corps doit dépasser une page de code à l'écran; laissant comment l'objet est atteint au code dans le corps de la fonction

Lorsque je lis le code des autres (principalement du langage C), si les noms de variable / fonction ne sont pas intuitifs dans le contexte du projet ou s'il dépasse cinq niveaux d'indentation ou si les fonctions prennent plus de six ou sept arguments ou si une fonction s'exécute deux ou trois pages à l’écran, il devient très difficile de lire et de comprendre le code. Lorsqu'on lui demande d'effectuer des travaux d'amélioration / de maintenance, cela ne fait qu'ajouter à la difficulté. Cela me fait souhaiter gofmtque le programme soit écrit pour chaque projet (ou même la langue) et que chaque fichier de code source soit exécuté dans ce programme avant qu'il ne soit validé dans le projet.

J'aime le Guide des styles JavaScript de Google .

Son concis dans ses directives a encore des détails si vous en avez besoin.

Code auto-documenté (commentaires, noms de variables, noms de fonctions, etc.)