Académique Documents
Professionnel Documents
Culture Documents
Par hugo
L'objectif de cet article est de tenter d'expliquer l'utilit des conventions de codage que nous rencontrons frquemment. Le but n'est pas uniquement de lister un ensemble de rgles mais surtout de donner une justification leur existence.
I - Introduction..............................................................................................................................................................3 II - Normes gnrales d'organisation du code............................................................................................................ 3 II-A - Taille des fichiers.......................................................................................................................................... 4 II-B - Taille des mthodes...................................................................................................................................... 4 II-C - Entte documentaire des classes et mthodes............................................................................................4 II-D - Pourcentage de commentaires dans le code...............................................................................................5 III - Normes gnrales de nommage.......................................................................................................................... 5 III-A - Packages......................................................................................................................................................5 III-B - Classes.........................................................................................................................................................5 III-C - Variables.......................................................................................................................................................6 III-D - Constantes................................................................................................................................................... 6 III-E - Artefact (jar)................................................................................................................................................. 6 III-F - Standard Directory Layout (projet maven)...................................................................................................6 IV - Conventions relatives la lisibilit....................................................................................................................... 7 IV-A - Indentation du code..................................................................................................................................... 7 IV-B - Taille des lignes........................................................................................................................................... 8 IV-C - Encodage des fichiers................................................................................................................................. 9 IV-D - Retour la ligne Windows/unix.................................................................................................................. 9 V - Conclusion............................................................................................................................................................. 9 V-A - Remerciements............................................................................................................................................. 9 V-B - Rfrences....................................................................................................................................................9
-2Copyright 2009 hugo. Aucune reproduction, mme partielle, ne peut tre faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu' trois ans de prison et jusqu' 300 000 de dommages et intrts. Cette page est dpose la SACD.
http://hugo.developpez.com/tutoriels/genie-logiciel/utilite-normes-codage/
I - Introduction
Faisons un sondage rapide, combien de fois avez-vous dj maudit ou entendu maudire les "normes de codage" ? Des dizaines, des centaines, des miliers de fois ? Encore faut il que vous ayez dj entendu cette expression. Si c'est le cas, il y a de grandes chances que vous travailliez sur du dveloppement informatique et cet article peut vous intresser. Car finalement c'est quoi ces "normes de codage" ? Passons les prjugs communs : Une faon d'uniformiser les individus ? ("Je ne suis pas un numro !") Une entrave l'imagination pos par votre hirarchie pour limiter vos prises d'initiatives et les rassurer ?
Elle est loin l'poque des gnies dans leurs garages o l'informatique s'apparentait plus l'artisanat. Aujourd'hui La cration logicielle tend dsormais vers un processus industriel bien rod. L'heure n'tant plus l'artisanat, l'informatique tend normaliser ces processus : codage, mthodologies de test, de conduite de projet etc... Souvent mal peru, car mal expliqu, on oublie l'objectif des normes de codages qui sont apparus suite un constat simple dont on retrouve un condens sur le site de Sun 80% du temps pass dans le cycle de vie d'un logiciel intervient pendant le cycle de maintenance Il est trs rare qu'un code soit maintenu par son auteur original De bonnes conventions adoptes par tous permettent un dveloppeur de s'y retrouver plus facilement dans un code inconnu
Et c'est tout le but de ces normes, simplifier la maintenance et faciliter une comprhension universelle. On remarqueras notamment dans cet article que l'un des premiers conseils pour amliorer du code que l'on maintient est avant tout de le remettre aux normes. La remise aux normes est un pralable aux oprations de refactoring ! Attention cependant la cohrence de codage. Restez cohrent par rapport l'existant, au minimum par module. Et sachez aussi quand il ne faut pas tre dans les normes. C'est d'ailleurs l'un des conseils sur le site des normes de codage Python. Parfois il faut enfreindre les standards si cela peut dgrader la lisibilit ou si ces standards sont diffrents de ceux de votre vieille application qui a 20 ans et dont vous avez hrit avec plaisir. A vous de juger du juste quilibre entre le refactoring ncessaire et le temps disponible, en gardant l'esprit l'objectif : amliorer la maintenance future. A charge d'exemple, je dtaillerais un ensemble des rgles simples. Le but n'tant pas d'dicter des rgles absolues mais bien d'expliquer leurs raisons d'tre. Les chiffres donns plus bas et suivi d'un (*) sont des mtriques tablies sur la base de l'exprience et peuvent ne pas s'appliquer tout les cas possibles. A vous de les adapter selon vos projets et votre exprience. En aucun cas je ne prtends donner de rgles d'or.
-3Copyright 2009 hugo. Aucune reproduction, mme partielle, ne peut tre faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu' trois ans de prison et jusqu' 300 000 de dommages et intrts. Cette page est dpose la SACD.
http://hugo.developpez.com/tutoriels/genie-logiciel/utilite-normes-codage/
A noter que l'on peut trouver un certain nombre d'adversaires la documentation dans le code argumentant que le code doit tre suffisament explicite pour se comprendre tout seul si un dveloppeur apporte une modification, la documentation est souvent mise de ct, ce qui entraine des commentaires faux et source d'erreur l'avenir.
Personnellement je vous encouragerais maintenir une documentation de qualit dans le code. Effectivement le code doit pouvoir se comprendre, mais sur un applicatif de plus de 50 000 lignes de code vous aurez sans doute mieux faire ces 5 prochaines annes que de tout relire. Je vous encourage lire cet article d'IBM sur le sujet. La documentation de l'entte dcrit une boite noire dont vous n'avez pas l'obligatoire de tout connatre, elle doit tre complte et mise jour. Elle contient au minimum pour les mthodes : La liste des paramtres et leur signification si besoin Le retour attendu Les exceptions/erreurs renvoyes (selon les languages) Un court descriptif de la mthode
Pour les classes, une description, mme succinte. Une description complte tant bien sr prfrable. Exemple : Javadoc de la mthode add de ArrayUtils
-4Copyright 2009 hugo. Aucune reproduction, mme partielle, ne peut tre faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu' trois ans de prison et jusqu' 300 000 de dommages et intrts. Cette page est dpose la SACD.
http://hugo.developpez.com/tutoriels/genie-logiciel/utilite-normes-codage/
III-A - Packages
Tout en minuscule Utiliser uniquement [a-z][0-9] et le point. Tout package doit avoir comme root : com, edu, gov, mil, net, org ou les deux lettres identifiants un pays (code ISO).
III-B - Classes
Premire lettre en majuscule Mlange de minuscule, majuscule avec la premire lettre de chaque mot en majuscule Donner des noms simples et descriptifs Eviter les acronymes hormis les communs (Xml, Url, Html) N'utiliser que des lettres [a-z][A-Z] et [0-9] Il s'agit de la mme convention en C++.
-5Copyright 2009 hugo. Aucune reproduction, mme partielle, ne peut tre faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu' trois ans de prison et jusqu' 300 000 de dommages et intrts. Cette page est dpose la SACD.
http://hugo.developpez.com/tutoriels/genie-logiciel/utilite-normes-codage/
Le nom d'une classe n'est jamais un verbe, ou plus gnralement une action. On a donc une classe qui peut s'appeler "BiduleBuilder", car c'est un constructeur de bidule. Mais pas BiduleBuild. On utilise la grammaire anglaise, soit donc "BiduleBuilder" et pas "BuilderBidule".
III-C - Variables
Premire lettre en minuscule Mlange de minuscule, majuscule avec la premire lettre de chaque mot en majuscule Donner des noms simples et descriptifs Variable d'une seule lettre viter au maximum sauf dans des cas prcis et locaux (tour de boucle) N'utiliser que des lettres [a-z][A-Z] et [0-9]
III-D - Constantes
Tout en majuscule Sparer les mots par des underscore Donner des noms simples et descriptifs N'utiliser que des lettres [a-z][A-Z] et [0-9]
La description ci dessous n'est pas complte, rfrez vous au site officiel pour plus d'informations. Rpertoire Description
-6Copyright 2009 hugo. Aucune reproduction, mme partielle, ne peut tre faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu' trois ans de prison et jusqu' 300 000 de dommages et intrts. Cette page est dpose la SACD.
http://hugo.developpez.com/tutoriels/genie-logiciel/utilite-normes-codage/
Sous xemacs j'ai configur mon diteur pour mettre afficher des tabulations de 4 caractres et. Cependant j'ai aussi prcis que l'indentation du code s'effectuait avec des espaces et non des caractres tabulations. Je modifie une ligne et ca apparait correctement chez moi puisque j'affiche 4 espaces pour les tabulations. Programme correctement modifi sous xemacs
public class MyApp { public static void main (String[] args) { System.out.println("Hello World"); } }
Je rouvre sur eclipse, la ligne modifie comporte dsormais 4 espaces alors que mes tabulations de 8 sont restes. Programme ouvert de nouveau avec eclipse
public class MyApp { public static void main (String[] args) { System.out.println("Hello World"); } }
Dans cette configuration, les sources crits avec eclipse et ouverts sous xemacs sont tasss gauche, alors que les sources crits avec xemacs et ouverts sous eclipse sont dports trop droite. L'effet rendu est trs dsagrable sur des fichiers ayant t dits par plusieurs diteurs. Certains languages sont encore plus stricts sur les identations, c'est notamment le cas de Python qui n'acceptera pas le mix des tabs et des espaces si vous utilisez certaines options de compilation. N'oubliez pas, en Python, l'indentation est le seul repre permettant de dterminer le dbut et la fin d'un bloc !
-7Copyright 2009 hugo. Aucune reproduction, mme partielle, ne peut tre faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu' trois ans de prison et jusqu' 300 000 de dommages et intrts. Cette page est dpose la SACD.
http://hugo.developpez.com/tutoriels/genie-logiciel/utilite-normes-codage/
Etablir une limite 300 dans Eclipse permet de dsactiver ces csures automatiques. A charge du dveloppeur de les faire intelligemment et lisiblement. Les csures automatiques combin avec l'utilisation d'accolades en fin de ligne (oui je suis minoritaire sur ce point mais je dteste les accolades en fin de ligne ^^) peuvent donner un code de ce type : Mthode toMap de ArrayUtils avec les conventions sun
public static Map toMap(final Object[] array) { if (array == null) { return null; } final Map map = new HashMap((int) (array.length * 1.5)); for (int i = 0; i < array.length; i++) { Object object = array[i]; if (object instanceof Map.Entry) { Map.Entry entry = (Map.Entry) object; map.put(entry.getKey(), entry.getValue()); } else if (object instanceof Object[]) { Object[] entry = (Object[]) object; if (entry.length < 2) { throw new IllegalArgumentException("Array element " + i + ", '" + object + "', has a length less than 2"); } map.put(entry[0], entry[1]); } else { throw new IllegalArgumentException("Array element " + i + ", '" + object + "', is neither of type Map.Entry nor an Array"); } } return map; }
http://hugo.developpez.com/tutoriels/genie-logiciel/utilite-normes-codage/
return null; } final Map map = new HashMap((int) (array.length * 1.5)); for (int i = 0; i < array.length; i++) { Object object = array[i]; if (object instanceof Map.Entry) { Map.Entry entry = (Map.Entry) object; map.put(entry.getKey(), entry.getValue()); } else if (object instanceof Object[]) { Object[] entry = (Object[]) object; if (entry.length < 2) { throw new IllegalArgumentException("Array element " + i + ", '" + object + "', has a length less than 2"); } map.put(entry[0], entry[1]); } else { throw new IllegalArgumentException("Array element " + i + ", '" + object + "', is neither of type Map.Entry nor an Array"); } } return map; }
A vous de juger...
V - Conclusion
Cet article aura permis je l'espre d'expliquer certaines conventions de nommage et leur utilit. Les exemples dans ce document ne sont pas prendre au pied de la lettre et je vous invite prendre un certain recul avant de les adopter. Il est bien videmment possible de les adapter mais gardez toujours l'esprit l'objectif de ces normes : leur universalit !
V-A - Remerciements
Je tiens remercier *** pour leurs corrections et leur aide la publication de cet article.
V-B - Rfrences
Conventions de codage C++ (Coding standards.com)
-9Copyright 2009 hugo. Aucune reproduction, mme partielle, ne peut tre faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu' trois ans de prison et jusqu' 300 000 de dommages et intrts. Cette page est dpose la SACD.
http://hugo.developpez.com/tutoriels/genie-logiciel/utilite-normes-codage/
Conventions de codage C++ (Possibility.com) Conventions de codage Python (Python) Conventions de codage Java (Sun) Conventions de nommage Java (Sun) Conventions de nommage Java (loribel.com) Conventions de nommage Java (developpez.com) Mauvais code selon javaworld article d'IBM sur la ncessit de commenter son code Standard directory layout maven Standard directory layout maven (documentation codehaus) Guide francophone des conventions de codage pour la programmation en langage Java (Cyberzoide - Developpez.com) Les outils de suivi de qualit en Java (arodrigues - Developpez.com)
- 10 Copyright 2009 hugo. Aucune reproduction, mme partielle, ne peut tre faite de ce site et de l'ensemble de son contenu : textes, documents, images, etc. sans l'autorisation expresse de l'auteur. Sinon vous encourez selon la loi jusqu' trois ans de prison et jusqu' 300 000 de dommages et intrts. Cette page est dpose la SACD.
http://hugo.developpez.com/tutoriels/genie-logiciel/utilite-normes-codage/