Sie sind auf Seite 1von 10

Utilit des normes de codage

Par hugo

Date de publication : 27 mars 2009

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.

Utilit des normes de codage par hugo

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/

Utilit des normes de codage par hugo

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.

II - Normes gnrales d'organisation du code


Dans ce premier chapitre, nous aborderons des conventions relatives l'organisation et au dcoupage de votre code.

-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/

Utilit des normes de codage par hugo

II-A - Taille des fichiers


En rgle gnrale, on s'accorde sur le fait qu'un fichier ne doit pas dpasser 1000 (*) lignes de codes. On peut videmment souligner qu'un fichier est difficile relire dpass cette limite mais au del de a, pour un programme voulant respecter le paradigme objet, des fichiers trs longs (plusieurs milliers de lignes) sont souvent l'expression d'un mauvais dcoupage des traitements, i.e. d'une mauvaise comprhension de la conception/dveloppement orient objet. De tels fichiers traduisent gnralement la prsence de classes gestionnaires , ayant accs toutes les donnes possibles et imaginables et connaissant l'essentiel du fonctionnel. Or chaque classe devrait tre responsable des traitements qui lui sont propres.

II-B - Taille des mthodes


Il est dconseill d'crire des mthodes de plus de 100 (*) lignes. Certains traitements peuvent nanmoins justifier un dpassement de ce nombre de lignes, mais des mthodes trop longues traduisent un mauvais dcoupage d'algorithme et conduisent gnralement l'obtention d'un code incomprhensible, suites aux diverses actions correctives qui y seront apportes.

II-C - Entte documentaire des classes et mthodes


Les enttes documentaires permettent de spcifier le comportement de votre applicatif. Ne perdez jamais l'esprit que votre code sera un jour lu par une autre personne, l'absence de documentation obligera vos successeurs faire de la rtro conception partir du code. Voici une petite liste d'outils pour la documentation : Javadoc : exemple de Javadoc Doxygen, outil utilis en C++, C, Java, Objective-C, Python, IDL, Fortran, VHDL, PHP, C#, et un peu en D

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/

Utilit des normes de codage par hugo

II-D - Pourcentage de commentaires dans le code


Le pourcentage de commentaires dans le code devrait tre hauteur de 20% (*) des lignes crites. Les commentaires permettent de suivre des algorithmes complexes ou de suivre le cheminement logique d'une chane de traitement. S'ils peuvent paratre superflus lors de la phase de dveloppement, ils seront indispensables lors de la phase de maintenance pour les personnes qui prennent le relais d'un code qu'ils n'ont pas crit eux-mmes. Ce point fait sans doute parti des points les plus difficiles faire accepter. Pourquoi crire des commentaires puisque j'ai dj une Javadoc. Et d'ailleurs beaucoup des projets open source que j'utilise ne commente son code. Attention justement ne pas confondre la Javadoc qui dcrit la boite noire que constituent votre mthode et le commentaire interne qui dcrit son fonctionnement. De plus, si vous utilisez des librairies open source et que vous avez dj du dbugger certaines d'entre elles, il y a fort parier que justement vous auriez bien aim plus de commentaires parfois.

III - Normes gnrales de nommage


Dans la suite de ce chapitre, nous reprendrons les principaux points dvelopps par SUN et suivies par la communaut Java. De faon gnrale, tous les noms doivent tre en anglais. Certains points peuvent s'appliquer d'autres languages mais nous dcrirons ici des conventions qui peuvent tre spcifiques. Les conventions de nommage font sans doute partie des conventions de codage les plus lies la lisibilit. Veuillez vous rfrer la partie rfrences pour les sources ayant permis de rdiger les paragraphes suivant. On pourra remarquer dans certaines socits des conventions supplmentaires issus bien souvent d'autres langages. Par exemple : Prfixage des variables par le type, la porte etc... (language : C, C++, python, PHP, etc...). A noter que ces conventions se justifient pour des languages non types comme le python ou le PHP et pour des quipes qui n'ont pas la possibilit d'utiliser des IDE performants (avec mise en couleur selon la porte et infos bulles sur les variables). Cependant si vous utilisez un language typ avec un bon IDE ce type de notation surchargera inutilement votre code. Prfixage des mthodes prives par des "__". (language : python). Parfait exemple de conventions dconseiller pour les langages dont ce n'est pas la norme. Vouloir retranscrire les normes que l'on connat dans un autre language a bien souvent pour rsultat de produire l'effet inverse l'effet escompt, ce n'est plus une norme puisque vous tes le(s) seul(s) l'utiliser.

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/

Utilit des normes de codage par hugo

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]

III-E - Artefact (jar)


Cette convention n'est pas hrit de SUN mais de la communaut open source en gnrale : Tout en minuscule Sparer les mots par des N'utiliser que des lettres [a-z][A-Z] et [0-9] Le numro de version apparat la fin du nom spar par un La version est numrique On peut utiliser des acronymes selon les cas : alpha, beta, RC, ga etc...

III-F - Standard Directory Layout (projet maven)


Cette convention est essentiellement applicable au monde Java. Je la dcris ici car elle donne un bon exemple de l'avantage de suivre des conventions. Maven est un outil de build utilis principalement dans le monde Java. L'un de ces leitmotiv est : "conventions over configurations", autrement dit prfrer les conventions une plthore de configurations : si tant est que vous respectiez des conventions gnrales, l'outil doit tre facile mettre en place. Son adoption grandissante dans la communaut Java vous garantit qu'en changeant de projet vers un autre projet qui utilise maven vous ne serez pas dpays par l'organisation. Pour plus d'infos en franais sur maven et l'organisation des fichiers : Utiliser maven2

La description ci dessous n'est pas complte, rfrez vous au site officiel pour plus d'informations. Rpertoire Description

src/main/java src/main/resources src/main/webapp src/test/java src/test/resources

Source Ressources Source d'une webapp Source de test Ressources de test

-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/

Utilit des normes de codage par hugo

IV - Conventions relatives la lisibilit


Dans ce chapitre nous allons aborder les rgles de codage li dont certaines sont lies avec l'diteur utilis. En prenant mon exprience professionnelle en compte, j'ai modifi lgrement les conventions utilises dans eclipse. Comme pour les autres chapitres, je vous invite rester proche des conventions officielles mais cela n'empche pas de rester critique leur encontre

IV-A - Indentation du code


L'ensemble du code devrait tre indent de faon similaire. De plus, les diteurs de code devraient tre configurs de manire remplacer les tabulations par des blancs. De cette faon, des diteurs diffrents peuvent tre utiliss en fonction des affinits de chacun tout en obtenant un rsultat identique. Prenons un cas de figure simple. Cidessous un bout de code indent avec des tabulations. Sous eclipse j'aai prcis qu'une tabulation reprsentait un espacement de 8 caractres Programme correctement indent avec tabulations
public class MyApp { public static void main (String[] args) { System.out.println("Hello World"); } }

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/

Utilit des normes de codage par hugo

IV-B - Taille des lignes


La lecture du code lors des phases de maintenance se fait de bas en haut et l'utilisation d'une barre de dfilement horizontal est pnalisante la lecture. C'est pourquoi on limite en gnral la taille d'une ligne 180 caractres qui correspondent la largeur d'un cran. A noter que plusieurs languages encouragent une longueur de ligne maximale 80 caractres. Par exemple le style d'dition par dfaut dans Eclipse limite 80 caractres la taille des lignes. 80 caractres correspondent la taille des crans si toutes les vues Eclipse sont affiches. Pour Python, il s'agit de prendre en compte d'autres types de devices limit 80 caractres. La taille limite est donc dterminer en fonction de vos besoins, des outils utiliss par les membres de votre quipe ainsi que de la taille de leurs crans. En tant qu'exemple personnel, je travaille dans une quipe qui utilise Eclipse sur des crans 22 pouces. Nous avons dcid de ne pas utiliser la limitation 80 caractres pour deux raisons principales : Le reformatage automatique d'Eclipse tablit des csures automatiques en dpit de la logique 80 caractres gchent une grande place l'cran non ncessaire en mode dition plein cran.

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; }

la mme sans les csures automatiques


public static Map toMap(final Object[] array) { if (array == null) {
-8Copyright 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/

Utilit des normes de codage par hugo

la mme sans les csures automatiques

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...

IV-C - Encodage des fichiers


La lecture du code peut tre grandement pnalise si les fichiers sont dits avec des encodages diffrents. En effet les accents et autres caractres particuliers apparaissent sous la forme de carr ou autres bizarreries. Ces diffrences peuvent tre pnalisantes pour les fichiers de ressource, les fichiers sql etc... Quelque soit la convention que vous utilisez, faites en sorte d'avoir la mme pour tout le monde.

IV-D - Retour la ligne Windows/unix


Afin d'viter les Ctrl+M dans les fichiers, il est ncessaire de spcifier le type de retour la ligne dans l'diteur de fichier.

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/

Utilit des normes de codage par hugo

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/