it-swarm-fr.com

Que devrait être dans une norme de codage?

Que devrait-il être dans une norme de codage de bonne (lecture: utile)?

  • Choses que le code devrait avoir.
  • Choses que le code ne devrait pas avoir.
  • Si la norme de codage inclut les définitions des choses que la langue, le compilateur ou le formulaire de code applique-t-il?
  • Qu'en est-il des métriques comme la complexité cyclomatique, les lignes par fichier, etc.?
34
C. Ross

Une raison pour toutes les exigences. Ainsi, après la norme ne devient pas une sorte de culte de cargaison et que les gens savent qu'il est correct de changer la norme si la raison de cela ne s'applique plus ou de violer la norme dans des cas spécifiques où la raison ne s'applique clairement pas. .

40
dsimcha

Onglets vs espaces! Je reçois des mises à jour folles lorsque l'un de mes collègues engage accidentellement beaucoup d'onglets aux espaces changés dans le référentiel

20
Fede

Conventions de nommage

Edit : Par ceci, je veux dire nommer des directives, pas de nommage.

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

19
Rachel

Une norme de codage pour un groupe doit inclure les options du compilateur pour les avertissements et les erreurs qui doit être adressée.

Les programmeurs doivent être libres d'augmenter augmenter avertissements pour leur propre code, mais il doit y avoir une base de référence afin que la lecture et le travail avec le code de quelqu'un d'autre n'entendit pas la sortie que vous obtenez du compilateur.

Une telle norme devra également répondre à la manière dont les programmeurs peuvent désactiver ces avertissements cas par cas, s'il y a une pièce de code exceptionnelle qui ne sera pas conforme autrement.

10
Macneil

Certaines normes que j'aime (je sais qu'il y en a beaucoup, mais c'est ceux que je préfère):

  • Couverture de tests d'unité 80%
  • Propriété collective du code (code d'écriture à lire par vos coéquipiers, pas le compilateur)
  • Écrire des commentaires. Ecrivez ce que vous diriez à un nouveau venu.
  • Rester simple
9
user2567

Les normes de codage vous aident un peu lorsque vous écrivez le code la première fois, ils aident un lot lorsque vous, ou votre remplacement, doit mettre à jour le code 2 des années plus tard.

La norme idéale conduit à un code dans lequel vous pouvez passer à n'importe quelle page arbitraire du code et comprendre de manière excédente ce qu'elle fait sur la première lecture, car

  • les noms décrivent clairement quelles données sont manipulées,
  • les bretelles 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 de code d'écriture. Je pense donc que chaque article d'une convention de codage proposé doit être évalué à l'encontre de ces 2 critères:

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

Si cela n'est pas vrai, l'article est juste arbitraire et probablement inutile


J'inclus les choses suivantes dans une norme j'écris:

Pour plus de clarté:

  • Organisation de fichier: La spécification d'une commande fixe pour les éléments d'un fichier permet à l'équipe de naviguer facilement à d'autres fichiers. Vous ne devriez pas avoir à chasser pour trouver #defines ou des définitions de structure.

  • Nommage Conventions: Lisibilité cohérente du sida de dénomination. Mais évitez de trop spécifier trop de règles, ce qui nuit à la critère.

  • Structure de code. Placement de l'attelle bouclée, niveaux d'indentation, espaces vs onglets, etc. Oui, cela peut être une préférence personnelle forte, mais le but est clair. Trouvez la meilleure option pour l'équipe et tenez-la avec elle.

Pour l'exactitude:

  • Meilleures pratiques spécifiques à votre type de problème: règles relatives à la répartition de la mémoire, à la simultanée ou à la portabilité.

  • "Consorsnesss", utilisation correcte de static et volatile, etc.

  • Règles sur les macros de préprocesseur et d'autres caractéristiques facilement abusées de la langue.

7
AShelly

Des idées pragmatiques inspirantes qui font penser aux 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 le bananes .

6
Alan Pearce

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

Pas parce que je suis un codoyer de cow-boy qui ne veut pas de processus, mais parce que j'ai vu des spécifications de codage lourdes sans logique derrière elle au-delà (vraisemblablement), j'ai trouvé cela sur le "Net quelque part en arrière" 95 "qui finissent par devenir un cauchemar bureaucratique pour travailler avec.

Certaines personnes semblent honnêtement croire qu'en démolissant les normes, elles verront une augmentation correspondante de la "qualité" de code et peut-être de cette mesure qu'ils le feront. Entre-temps, ils ignoreront l'architecture, la performance, le bon sens et une bouquet d'autres choses qui finissent plus que le nombre de lignes dans un fichier.

4
Rodney Gitzel

Une procédure pour les critiques de code pour appliquer la norme. Oh, et pour trouver des bugs aussi.

3
Dima

Un bon vieux bon sens ne serait pas ira mal; Il y a beaucoup trop de documents standards de codage qui travaillent sur des points non pertinents (articles tels que type de police et taille étant l'un des plus extrêmes que j'ai vus).

La meilleure chose à faire si vous êtes dans un groupe de développeurs, c'est se parler et regarder votre code, former un consensus sur ce qui est acceptable et si vous avez besoin d'écrire les points principaux en tant que directives, mais conservez-les comme Juste cette directive. Si vous ne pouvez pas justifier une divergence des directives, vous devriez vraiment considérer pourquoi vous le faites.

À la fin de la journée, le code clair et compréhensible est plus important que toute règle rigide sur la mise en page ou la typographie.

3
GrumpyMonkey

J'aime le format dans les lignes directrices de conception-cadre Il comprend une section générale et des rationnels pour les lignes directrices. Les bits les plus utiles sont les détails qui commencent par faire, ne sont pas, évitez et considèrent.

Voici un exemple dans la section - Miluisement des membres de l'interface explicitement Il a les éléments suivants (note que j'ai laissé tomber les raisons pour la Bervity's Sake)

Éviter Mise en œuvre explicitement des membres de l'interface sans avoir une raison forte de le faire

envisagez Mise en œuvre explicitement des membres de l'interface si les membres sont destinés à être appelés uniquement à travers l'interface.

Ne pas Utilisez des membres explicites comme une limite de sécurité.

DO Fournissez un élément virtuel protégé qui offre la même fonctionnalité que l'élément> Efficitement mis en œuvre si la fonctionnalité est destinée à être spécialisée par des classes dérivées.

Cela crée un bon ton général. En utilisant l'évité et envisagez que vous puissiez permettre aux développeurs d'utiliser leur jugement. En outre, parce que ce sont des lignes directrices et non les développeurs de règles sont susceptibles de les trouver plus agréables et plus susceptibles de les suivre.

2
Conrad Frix

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

  • Structure du projet. Les tests font-ils partie du code ou sont-ils dans un projet/package/répertoire distinct? Le code UI vivre-t-il avec les trucs back-end? Sinon, comment est-il compartimenté?

  • Processus de développement. Écrire des tests avant le code? La fixation des constructions cassées prend-elle la priorité sur le développement? Quand les commentaires sont-ils effectués et que doivent-ils couvrir?

  • Gestion de code source. Ce qui est enregistré quand? Les documents de conception sont-ils contrôlés par la révision? Quand branche-tu et quand tagez-vous? Conservez-vous les constructions précédentes et si oui combien de temps?

  • Normes de déploiement. Comment une entreprise est-elle emballée? Qu'est-ce qui doit aller dans des notes de publication? Comment les scripts de mise à niveau sont-ils créés/contrôlés/exécutés?

Oubliez toute cette merde sur la dénomination des conventions, le formatage et le nombre de lignes peuvent être dans une fonction/procédé/module. Une règle: utilisez tout ce que le style existant est dans tout ce que vous êtes édition. Si vous n'aimez pas le style de quelqu'un, choisissez-le dans une critique de code. La seule exception pourrait être la chose des onglets-vs-espaces, si seulement parce que de nombreux éditeurs/IDes convertiront aveuglément l'une à l'autre, puis vous détruisez la destruction de votre historique de changement car chaque ligne a été modifiée.

2
TMN

Je pense qu'il y a en fait deux choses à traiter et je les considère en fait séparément parce qu'elles ne peuvent être approchées de la même manière, même si je trouve les deux importants.

  • L'aspect technique: qui vise à éviter du code risqué ou mal formé (même s'il est accepté par le compilateur/interprète)
  • L'aspect présentation: qui se préoccupe de rendre le programme clair pour les lecteurs

L'aspect technique que je qualifie de Norme de codage, de même que herbe sutter et Andrei Alexandrescu avec leurs normes C++ Codage. La présentation que je qualifie de Style de codage, qui comprend la convention de dénomination, l'indentation, etc ...

Standard de codage

Parce qu'il est purement technique, une norme de codage peut être principalement objective. En tant que telle règle devait être soutenue par une raison. Dans le livre, j'ai mentionné chaque article a:

  • Un titre, simple et au point
  • Un résumé, qui explique le titre
  • Une discussion, qui illustrant la question de ce faisant autrement et indique donc la logique
  • Facultatif Quelques exemples, car un bon exemple vaut mille mots
  • Facultatif une liste d'exceptions pour lesquelles cette règle ne peut pas être appliquée, parfois avec des contours de travail
  • Une liste de références (autres livres, sites Web) qui ont discuté de ce point

Justification et exceptions sont très importantes, car ils résument la raison pour laquelle et quand.

Le titre est suffisamment explicite que pendant les critiques, il suffit de disposer d'une liste de titres (feuille de triche). Et évidemment, regroupez les articles par catégorie pour faciliter la recherche d'un.

Sutter et Alexandrescu ont réussi à avoir une liste de centaines d'articles, même si C++ est jugé velu;)

Style de codage

Cette partie est généralement moins objective (et peut être transversale subjective). L'intention ici est de garantir la cohérence, car cela aide les responsables et les nouveaux venus.

Vous ne voulez pas entrer dans une sainte guerre sainte à propos de laquelle l'indentation ou le style Brace est meilleur ici, il y a des forums pour cela: Donc, dans cette catégorie, vous faites des choses par consensus> Vote à la majorité> Décision arbitraire de la ou des chefs (s).

Pour un exemple de formatage, voir la liste des options de style artistique . Idéalement, les règles doivent être claires et assez complètes pour qu'un programme puisse réécrire le code (même s'il est improbable que vous en déconnectez jamais.))

Pour la convention de dénomination, j'essaierais de rendre les classes/types facilement distingués des variables/attributs.

C'est aussi dans cette catégorie que je classes les "mesures" comme:

  • préfèrent des méthodes courtes à longues: il est généralement difficile d'être d'accord sur ce qui est long
  • préfère le retour rapide/continuer/rompre pour réduire l'indentation

misc ?

Et en tant que mot final, il y a un élément qui est rarement, si jamais, discuté dans les normes de codage, peut-être parce qu'il est particulier à chaque application: organisation du code. La question architecturale est peut-être le problème le plus remarquable, bousillez-vous sur la conception initiale et vous en sévez à partir de maintenant. Vous devriez peut-être ajouter une section pour la manipulation des fichiers de base: en-têtes publics/privés, gestion de la dépendance, séparation des préoccupations, interfaçage avec d'autres systèmes ou bibliothèques ...


Mais ce sont rien s'ils ne sont pas réellement appliqués et appliqués .

Toute violation devrait être soulevée pendant les revues de code et aucun examen de code ne devrait être correct si une violation est exceptionnelle:

  • corrigez le code pour correspondre à la règle
  • réparer la règle afin que le code ne se démarque plus

De toute évidence, la modification d'une règle signifie que "aller de l'avant" des dirigeants.

2
Matthieu M.

Personne ne semble avoir mentionné la sécurité - dans une norme de codage, vous devez avoir une référence à sécuriser les exigences de code (par exemple, l'utilisation de modules de validation d'entrée, intersésive des fonctions faibles connues telles que Strcpy, les exigences de manutention des erreurs, etc.)

1
Rory Alsop

exemples. Des exemples soigneusement arrangés, non triviaux et fermés, qui utilisent toutes les règles. Commentaires (pas nécessairement une partie du code) Quelle partie de l'exemple suit la règle.

Modèles. Pas le type C++, mais quelque chose à copier-coller et à remplir avec en direct. Il est beaucoup plus facile d'obtenir ce commentaire de la chaudière de 24 lignes à droite lorsque vous avez une référence à copier.

1
user281377

Les normes de codage sont vraiment plusieurs articles:

Conventions de codage

  • ces choses n'ont pas besoin d'une raison autre que "consistance de la base de code" pour ex. utiliser '_' dans les variables de membre privé ou non.
  • il pourrait y avoir plusieurs approches correctes. Juste besoin de choisir un pour la cohérence. pour ex. Traitement des erreurs utilisant des exceptions ou des codes d'erreur.

meilleures pratiques

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

pour ex. Ne laissez jamais la prise vide après l'essai

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

1) S'il y a une exception projetée par FOO (), cela peut entraîner d'autres problèmes sur les fonctions qui suivent, qui supposaient que FOO ait réussi.

2) Global Error Manuturier ne fera pas informer l'équipe d'appui de l'exception lorsqu'elle se produise sur PROD

  • couvre les pratiques du "codage défensif", comme utiliser des affirmations pour tester vos hypothèses.

Environnement de codage

  • outils que l'ensemble de l'équipe utilise. pour ex. Vs 2010, Resharper, four, etc.
1
Mag20

caractéristique numéro une: un maximum absolu de deux pages.

C'est quelque chose que vous voulez que chaque développeur se lise et se souvienne. Vous ne devriez pas avoir à rechercher dans la norme chaque fois que vous devez écrire une nouvelle fonction (ou pire une nouvelle ligne). Donc, gardez-le court et ne conserve que les règles qui fournissent réellement une valeur accrue au produit final.

1

J'aime le Guide de style Google JavaScript .

Son concision dans ses lignes directrices n'a pas encore de détails si vous en avez besoin.

0
Sam Farmer

Les normes de codage, lorsqu'elles sont écrites sur papier, sont seulement tellement efficaces. J'aime comment ça va publier sa norme de codage. Il a l'outil gofmt pour formater le texte du programme à un format. Tout débat sur le format de codage résultera simplement d'un correctif aux sources de gofmt.

Quant à ce que le format devrait avoir,

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

Lorsque je lis, je lis les autres (cmérologie de la langue principalement), si les noms variables/fonctions ne sont pas intuitifs dans le contexte du projet ou si elle dépasse cinq niveaux d'indentation ou de fonctions, il faut plus de six ou sept arguments ou une fonction de fonction sur Deux ou trois pages à l'écran, il devient très difficile de lire et de comprendre le code. Lorsqu'on leur a demandé de faire des améliorations/maintenance, il ne fait qu'ajouter à la difficulté. Cela me fait un souhait gofmt tel que le programme est écrit pour chaque projet (ou même langue) et chaque fichier de code source doit être exécuté dans ce programme avant de s'engager dans le projet.

0
vpit3833