Création d'un document de normes de codage

Je travaille dans une entreprise de systèmes de contrôle, où le travail principal est SCADA et PLC , avec d'autres trucs de systèmes de contrôle.

Le développement de logiciels n'est pas vraiment quelque chose que l'entreprise fait, à part quelques petits morceaux ici et là, jusqu'à ce qu'il ait été décidé de créer un système interne de gestion de projet et d'évaluation.

Ce projet a été entrepris par des personnes qui sont venues ici en tant que personnes logicielles à l'origine et nous sommes pour la plupart juniors.

Le projet a commencé petit, nous n'avons donc documenté que des éléments comme la conception, les bases de données, etc., mais nous ne nous sommes jamais vraiment mis d'accord sur un format / des conventions de codage.

Nous avons commencé à utiliser StyleCop pour nous assurer que nous avions un code bien documenté, mais je pense que nous avons besoin d'un document officiel pour les conventions / pratiques de codage afin que nous puissions continuer un bon standard et s'il y a plus de travail de développement majeur à l'avenir, quiconque y travaillera a une bonne plaque de base.

C'est là que réside le problème, je ne sais pas comment rédiger un document pour les conventions et normes de codage, tout ce que je peux penser, ce sont des exemples de bonnes vs mauvaises pratiques (par exemple le cas du chameau lors du nommage des variables, en évitant la notation hongroise, etc.) nous sommes tous des programmeurs suffisamment compétents (apparemment) mais nous n'avons tout simplement pas de charte pour ce genre de choses.

Pour mettre un point là-dessus, ma question est la suivante: quels sont les principaux aspects et le contenu d'un bon document sur les normes de codage?

Quels sont les principaux aspects et contenus d'un bon document sur les normes de codage?

1. Être pris en charge par des outils qui permettent une vérification automatisée du code . Si je sais que je ne peux pas m'engager à contrôler la version d'un morceau de code qui ne correspond pas à certaines règles, je serais encouragé à suivre ces règles dans mon code. Si, d'autre part, certains collègues programmeurs ont écrit quelque part que je dois suivre une règle, je ne m'en fous pas de ces règles.

2. Être bien pensé, au lieu d'être votre opinion personnelle . Vous ne dites pas clairement: "à partir de maintenant, nous n'utilisons plus de régions, car je n'aime pas les régions". Vous expliquez plutôt que les régions encouragent la croissance du code et ne résolvent aucun problème majeur .

   La raison en est que dans le premier cas, votre collègue répondrait: "eh bien, j'aime les régions, donc je les utiliserais toujours". Dans le second cas, en revanche, cela obligerait les personnes en désaccord à formuler des critiques, des suggestions et des arguments constructifs, ce qui vous ferait éventuellement changer d'avis initial.

3. Être bien documenté . Le manque de documentation crée de la confusion et laisse place à l'interprétation ; la confusion et la possibilité d'interprétation entraînent une différence de style, c'est-à-dire ce que les normes veulent supprimer.

4. Être répandu, y compris en dehors de votre entreprise . Un «standard» utilisé par vingt programmeurs est moins standard qu'un standard connu par des centaines de milliers de développeurs à travers le monde.

Puisque vous parlez de StyleCop, je suppose que l'application est écrite dans l'un des langages .NET Framework.

Dans ce cas, sauf si vous avez de sérieuses raisons de faire différemment, respectez simplement les directives de Microsoft. Il y a plusieurs avantages à le faire plutôt qu'à créer vos propres normes. Prenant les quatre points précédents:

1. Vous n'avez pas besoin de réécrire les règles StyleCop pour qu'elles correspondent à vos propres normes. Je ne dis pas qu'il est difficile d'écrire vos propres règles, mais si vous pouvez éviter de le faire, cela signifie que vous avez plus de temps pour faire quelque chose d'utile à la place.

2. Les directives de Microsoft sont très bien pensées. Il y a des chances que si vous n'êtes pas d'accord avec certains d'entre eux, ce soit parce que vous ne les comprenez pas. C'était exactement mon cas; quand j'ai commencé le développement C #, j'ai trouvé quelques règles totalement stupides. Maintenant, je suis complètement d'accord avec eux, car j'ai finalement compris pourquoi ils étaient écrits de cette façon.

3. Les directives de Microsoft sont bien documentées, vous n'avez donc pas à rédiger votre propre documentation.

4. Les nouveaux développeurs qui seront embauchés plus tard dans votre entreprise connaissent peut-être déjà les normes de codage de Microsof. Il y a des chances que personne ne connaisse votre style de codage interne.

La première chose importante à noter est qu'un document sur les normes de codage ne concerne pas le bien et le mal. Il ne s'agit pas de bien ou de mal ou de la meilleure méthode.

Le but d'un document de normes de codage est de s'assurer que tout le code est conçu, écrit et présenté de la même manière pour permettre au développeur de passer plus facilement du travail d'une personne à une autre sans le changement de mentalité nécessaire pour lire le style de quelqu'un d'autre.

Tout est question d'uniformité, et rien de «bien et mal»

Dans cet esprit, certaines choses que vous devriez clarifier dans un document de normes de codage sont les suivantes:

Conventions de nommage

Comment nommerez-vous vos méthodes, variables, classes et interfaces? Quelle notation utiliserez-vous?

Un autre élément inclus dans nos normes était une norme séparée pour SQL, nous avions donc des noms similaires pour les tables, les procédures, les colonnes, les champs id, les déclencheurs, etc.

Échancrure

Qu'utiliserez-vous pour l'indentation? Un seul onglet? 3 espaces?

Disposition

Les accolades seront-elles conservées sur la même ligne que la ligne de méthode d'ouverture? (généralement java) ou sur la ligne suivante ou une ligne propre? (généralement C #)

Gestion / journalisation des exceptions

Quelles sont vos normes pour la gestion des exceptions et la journalisation, est-ce que tout est fait maison ou utilisez-vous un outil tiers? Comment doit-il être utilisé?

Commentant

Nous avons des normes pour dicter l'exactitude grammaticale, et que les commentaires commencent sur la ligne avant ou après, pas sur la même ligne, cela augmente la lisibilité. Les commentaires devront-ils être mis en retrait à la même profondeur que le code? Accepterez-vous ces bordures de commentaires utilisées autour de textes plus grands?

Que diriez-vous du \\\ sur les méthodes pour les descriptions? Doit-on les utiliser? Quand?

Exposition

Est-ce que toutes vos méthodes et tous vos domaines devraient implémenter le niveau d'accès le plus bas possible?

Aussi une chose importante à noter. Un bon document sur les normes peut grandement contribuer à réviser le code. Répond-il à ces normes minimales?

J'ai à peine gratté la surface de ce qui peut entrer dans l'un de ces documents, mais KISS

Ne le faites pas longtemps et ennuyeux et impossible à passer, ou ces normes ne seront simplement pas suivies, restez simples.

Je traversais ce processus plusieurs fois. Et l'approche la plus réussie (bien que cahoteuse de toute façon) était de prendre le document "Coding Standards" d'une entreprise bien connue et de le modifier pour l'adapter à vos besoins.

Par exemple, je viens de trouver celui-ci: http://www.tiobe.com/content/paperinfo/gemrcsharpcs.pdf

Quoi qu'il en soit, gardez votre lance-flammes à portée de main.

À votre santé,

Je déteste la plupart des documents standards car ils essaient généralement de transpirer les petits trucs et d'ignorer la vue d'ensemble.

Par exemple, presque tous diront comment nommer des variables ou placer des crochets. C'est un style pur et n'aide pas vraiment un groupe de développeurs correctement. Ils ignorent des choses comme la structure du répertoire et la disposition du code. J'ai vu des documents standards qui vous disaient exactement combien d'espaces mettre entre les opérateurs et combien de lignes vides mettre entre les méthodes. Tous ceux-ci se retrouvent généralement avec une tonne d'exceptions à la règle qui montre à quel point ils sont vraiment inutiles, puis ils sont si gros que personne ne peut les suivre, ce qui encore une fois, se moque du point qu'ils essaient de faire valoir .

Maintenant, pour moi, j'utilise de nombreux logiciels différents provenant de nombreuses personnes différentes et ils ont tous des styles différents. Je m'y habitue simplement, je ne me plains pas qu'il n'y ait pas de style commun à tous les groupes de développement. Tant que le code est un style commun tout au long d'un projet, je me fiche vraiment de ce style. Donc ma première règle pour tous les documents standards est: Gardez un style de codage cohérent dans le projet . personne ne devrait donner une figue où les crochets sont, tant qu'ils sont tous les mêmes. Prenez les guerres de religion et bousculez-les :)

Le second est la disposition du code. Quand je prends un morceau de code, je veux voir qu'il est disposé sur des lignes similaires à celles d'autres travaux similaires. Si j'ai un service Web, je veux que le nom du contrat wsdl soit clair, je veux que le nom de l'implémentation soit clair. Je ne veux pas que quelqu'un propose une mise en page nouvelle et différente pour les fichiers et les classes. Cela signifie que je dois jouer à "chasser le code", ce qui est une nuisance. Si cela ressemble au dernier projet sur lequel j'ai travaillé, je peux immédiatement savoir où trouver ce que je cherche et c'est probablement la plus grande aide que je connaisse pour travailler avec le code d'autres personnes. Donc, gardez une structure de la façon dont le code est présenté (par exemple, dossier de documentation pour les documents, interfaces pour les interfaces, etc. - quoi que ce soit qui fonctionne pour vous, mais respectez-le).

Des artefacts de code doivent également être présents, vous devez donc dire si la gestion des erreurs attendue est des exceptions ou des codes d'erreur - c'est-à-dire. documenter les fonctionnalités architecturales utilisées . Il devrait également indiquer quel type de journalisation utiliser et comment présenter les journaux / la gestion des erreurs à l'utilisateur ou tout autre sous-système utilisé pour gérer le code dans la nature. J'ai travaillé dans un endroit où chaque projet se connectait différemment - c'était pathétique de voir comment chaque version de code devait avoir son propre document d'exploitation différent, disant aux gars des opérations comment savoir si cela avait mal tourné. Le journal des événements, le fichier journal (dans ce cas, où), etc. sont tous valides ici. La même chose s'applique à d'autres aspects communs du code - comment le configurer (inutile d'utiliser un fichier .config pour certains programmes, ou une base de données personnalisée, ou des paramètres de ligne de commande, ou un registre pour d'autres).

Bref, la seule chose qui compte, c'est la cohérence . Et comme les énormes documents de normes sont trop lourds à lire et à mémoriser, je préfère simplement informer les gens des choses qu'ils ne peuvent pas voir (par exemple, les normes architecturales comme la journalisation) et leur dire de garder le code qu'ils écrivent cohérent avec ce qui existe actuellement. Et si vous n'avez pas déjà de code, vous n'avez pas besoin d'un document de normes! (enfin, pas avant d'avoir écrit suffisamment pour le rendre utile).

Prenez donc de là les points principaux: n'essayez pas de faire un document juridique , pensez à des choses qui ne sont pas seulement du codage mais aussi comment le code fonctionne et comment le code correspond aux attentes des autres. Faites ensuite confiance aux gens pour faire du bon code et vous verrez qu'ils le font. (et s'ils ne le font pas, vous pouvez avoir des mots avec eux, pas besoin de le poser comme la loi).

Non, c'est une perte totale de temps et d'énergie. StyleCop est génial et a été créé au fil des ans par des personnes beaucoup plus expérimentées et bien plus intelligentes que vous ou quiconque de votre équipe. Embrassez et aimez-le! Il vous guide en permanence, ce qui est mieux que tout document attendant que quelqu'un puisse être dérangé pour le lire.