Document de normes

Question

J'écris un document de normes de codage pour une équipe d'environ 15 développeurs avec une charge de projet comprise entre 10 et 15 projets par an.Entre autres sections (que je pourrai publier ici au fur et à mesure que j'y arrive), j'écris une section sur le formatage du code.Donc, pour commencer, je pense qu’il est sage que, pour une raison quelconque, nous établissions des normes de base et cohérentes en matière de formatage/dénomination du code.

J'ai examiné environ 10 projets écrits au cours des 3 dernières années par cette équipe et je trouve évidemment une gamme de styles assez large.Les entrepreneurs entrent et sortent de temps en temps, et parfois même doublent la taille de l'équipe.

Je recherche quelques suggestions de normes de formatage de code et de dénomination qui ont vraiment porté leurs fruits...mais cela peut aussi être vraiment justifié.Je pense que la cohérence et les modèles partagés contribuent grandement à rendre le code plus maintenable...mais y a-t-il d'autres éléments que je devrais prendre en compte lors de la définition desdites normes ?

• Comment aligner les parenthèses ?Suivez-vous les mêmes directives entre parenthèses lorsque vous traitez des classes, des méthodes, des blocs try catch, des instructions switch, des blocs if else, etc.

• Alignez-vous les champs sur une colonne ?Notez-vous/préfixez-vous les variables privées avec un trait de soulignement ?Suivez-vous des conventions de dénomination pour faciliter la recherche de détails dans un fichier ?Comment commandez-vous les membres de votre classe ?

Qu’en est-il des suggestions d’espaces de noms, d’empaquetage ou de normes de dossier/organisation de code source ?J'ai tendance à commencer par quelque chose comme :

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName

Je suis curieux de voir s'il existe d'autres pratiques, plus acceptées, que celles auxquelles je suis habitué - avant de m'aventurer à dicter ces normes.Des liens vers des normes déjà publiées en ligne seraient également très utiles, même si j'en ai déjà fait un peu.

Answer 1

Trouvez d’abord un formateur de code automatisé qui fonctionne avec votre langue.Raison:Quoi que dise le document, les gens enfreindront inévitablement les règles.Il est beaucoup plus facile d'exécuter du code via un formateur que de pinailler lors d'une révision de code.

Si vous utilisez un langage avec un standard existant (par ex.Java, C#), il est plus simple de l'utiliser, ou du moins de commencer avec cela comme première ébauche.Sun a beaucoup réfléchi à ses règles de formatage ;autant en profiter.

Dans tous les cas, rappelez-vous que de nombreuses recherches ont montré que des éléments variables tels que la position des accolades et l'utilisation des espaces n'ont aucun effet mesurable sur la productivité, la compréhensibilité ou la prévalence des bogues.Juste avoir n'importe lequel la norme est la clé.

Answer 2

Venant de l'industrie automobile, voici quelques standards de style utilisés pour des raisons concrètes :

Utilisez toujours des accolades dans les structures de contrôle et placez-les sur des lignes séparées.Cela élimine les problèmes liés aux personnes qui ajoutent du code et l'incluent ou ne l'incluent pas par erreur dans une structure de contrôle.

if(...)
{

}

Tous les commutateurs/sélections ont un cas par défaut.Le cas par défaut enregistre une erreur s'il ne s'agit pas d'un chemin valide.

Pour la même raison que ci-dessus, n'importe si... sinon...les structures de contrôle DOIVENT se terminer par un else par défaut qui enregistre également une erreur s'il ne s'agit pas d'un chemin valide.Une seule instruction if ne l'exige pas.

Dans le cas occasionnel où une boucle ou une structure de contrôle est intentionnellement vide, un point-virgule est toujours placé à l'intérieur pour indiquer que cela est intentionnel.

while(stillwaiting())
{
   ;
}

Les normes de dénomination ont des styles très différents pour les typedefs, les constantes définies, les variables globales des modules, etc.Les noms de variables incluent le type.Vous pouvez regarder le nom et avoir une bonne idée du module auquel il se rapporte, de sa portée et de son type.Cela facilite la détection des erreurs liées aux types, etc.

Il y en a d'autres, mais ceux-ci me viennent en tête.

-Adam

Answer 3

Je vais appuyer la suggestion de Jason.

Je viens de terminer un document de normes pour une équipe de 10 à 12 personnes travaillant principalement en Perl.Le document indique d'utiliser "une indentation de type perltidy pour des structures de données complexes". Nous avons également fourni à chacun des exemple de paramètres Perltidy qui nettoieraient leur code pour répondre à cette norme.C'était très clair et tout à fait conforme aux normes de l'industrie pour le langage, nous avons donc eu une grande adhésion de la part de l'équipe.

Lorsque j'ai décidé d'écrire ce document, j'ai demandé quelques exemples de code de qualité dans notre référentiel et j'ai cherché un peu sur Google pour trouver d'autres documents standards qui seraient des architectes plus intelligents que moi pour construire un modèle.C'était difficile d'être concis et pragmatique sans entrer dans le territoire des micro-managers, mais cela en valait vraiment la peine ;ayant n'importe lequel la norme est en effet essentielle.

J'espère que ça marchera !

Answer 4

Cela varie évidemment en fonction des langages et des technologies.D'après votre exemple d'espace de noms, je vais deviner Java, auquel cas http://java.sun.com/docs/codeconv/ est un très bon point de départ.Vous voudrez peut-être également examiner quelque chose comme la structure de répertoires standard de Maven qui rendra tous vos projets similaires.