On croit que le style est une façon compliquée de dire des choses simples, alors que c'est une façon simple de dire des choses compliquées (Jean Cocteau)==== Remarques générales ==== Un code informatique est souvent à l'image de l'état d'esprit de celui qui l'a écrit: organisé, bordélique, chaotique ou rigoureux... S'astreindre à adopter un style rigoureux d'écriture apporte aussi une rigueur dans sa manière de programmer. Voici quelques recommandations générales: - Règle d'or: adoptez UN style et conservez-le tant que vous le pourrez; - Si vous devez changer de style (compromis en projet par exemple), veillez à le définir très clairement par écrit; - Indentez votre code avec des tabulations, pas des espaces; - L'indentation de votre programme doit permettre d'en comprendre la structure; - Définissez la
Si le code et les commentaires se contredisent, les deux sont probablement faux. (Contradiction de Shryer)Un code conséquent non commenté vaut **PINUTS**; il est: * **P**énible (à lire); * **I**ncompréhensible (ou illisible); * **N**on **U**tilisable (par d'autre, ou par soi-même d'ailleurs, cf. infra); * **T**otalement **S**térile (on ne pourra rien produire à partir de lui).
Un code que vous avez écrit et que vous n’avez pas regardé depuis plus de six mois aurait très bien pu être écrit par quelqu’un d’autre.(Loi d’Eagleson)//Eagleson est optimiste, dans la réalité, c'est un mois...// Il existe deux types de commentaires en fonction du lecteur visé: * les commentaires pour le lecteur/programmeur du code
int i = 0;// tout ce qui se trouve après les // sur cette ligne est ignoré par le compilateur
/* tout
ce qui se trouve
après le /* est ignoré jusqu'au
prochain */
* les commentaires pour la documentation utilisateur (javadoc).
/** Il y a deux étoiles de suite: c'est un bloc de commentaire javadoc
Tout ce qui se trouve ici
@param sont des instructions
@return de documentation
@author qui peuvent utiliser
des marques
de formatage
*/
Les premiers peuvent être utilisés partout dans le code, dès que le programmeur souhaite indiquer des précisions dans le programme, expliquer une partie du code ou encore ignorer un passage du code (utile en débuggage par exemple).
Souvent, lorsqu'il s'agit de se rappeler que quelquechose doit être fait, le mot-clefs TODO est utilisé car de nombreux IDE sont capables de le repérer et de mettre en valeur le commentaire.
public int maFonction(){
/* je commente ce passage car ça marche pas
int ret = 0;
for(int i=2;i++;i
Les seconds servent à la documentation du programme en vue de sa réutilisation par d'autres (API).
Si ils sont bien utilisés, ils permettront de générer **automatiquement** des pages HTML contenant les informations sur les classes et le programme.
Ils se placent avant l'élément qu'ils décrivent. Dans l'idéal, ils devraient être écrit en français.
//Petite anecdote: lorsque j'ai commencé le projet [[http://natbraille.org|natbraille]], j'ai commenté tout mon code en français, vu que j'étais pratiquement le seul programmeur. Aujourd'hui que le projet a une portée internationale, les autres développeurs non francophones réclament des commentaires en anglais. Il va y en avoir pour pratiquement un mois temps rien qu'avec les commentaires, et un autre au moins pour les noms de classes et de variables du code... en français//
Voici par exemple le code de la classe {{:java:object.java|Object}} de java:
Et [[http://bruno.mascret.fr/ressources/java/docObj/java/lang/Object.html|le résultat produit]] avec la commande javadoc:
javadoc Object.java -d doc
Cette commande va créer les pages HTML de la documentation dans le répertoire **doc** (ouvrir index.html avec un navigateur web).
Vous constaterez au passage que **la plupart du code, c'est de la documentation!** (bien que simple, la classe Object est utilisée par tout le monde en java, il est important de fournir une documentation la plus exhaustive possible pour les programmeurs).
==== Quelques outils et liens ====
* [[http://www.oracle.com/technetwork/java/codeconvtoc-136057.html|La syntaxe recommandée par sun/oracle]]
* [[http://checkstyle.sourceforge.net/|Checkstyle]]: Un outil pour vérifier automatique son style
===== Bonnes habitudes pour la programmation =====
Quelques trucs pour éviter les ennuis...
==== En programmant ====
- utilisez des noms de classe/variables/méthodes PARLANT...
- ... et dans l'idéal en anglais!
- déclarez toujours dans le même ordre vos attributs, constructeurs, méthodes (éventuellement vos types de méthodes: accesseurs, puis méthodes implémentées, etc.);
- initialisez TOUJOURS un attribut, une variable... soit lors de sa déclaration, soit par l'intermédiaire du constructeur pour les attributs.
- ... ou faites-le systématiquement dans le constructeur;
- dès que vous ouvrez un bloc avec {, fermez-le immédiatement avec }:
for (int i=0;i<2;i++){
for (int i=0;i<2;i++){
}
for (int i=0;i<2;i++){
System.out.... etc
}
- si une méthode renvoie une valeur, écrivez-le tout de suite:
public int factorielle(int n){
public int factorielle(int n){
}
public int factorielle(int n){
int ret = 0;
return ret;
}
public int factorielle(int n){
int ret = 0;
if(n==1){
ret = 1;
}
else{
ret = n*factorielle(n-1);
}
return ret;
}
- Vous ne devriez JAMAIS quitter une méthode qui renvoie une valeur autre part qu'à la dernière ligne, et cette dernière ligne devrait contenir la seule instruction **return** de la méthode: méfiez-vous donc des instructions **break** et des **return** multiples;
==== En compilant ====
**Le compilateur est votre ami.**
Un compilateur ne s'use pas: n'ayez pas peur de l'utiliser à outrance.
**Votre confiance en la qualité de votre code devrait être inversement proportionnelle à votre fréquence de compilation!**
LISEZ le premier message d'erreur, comprenez-le, corrigez-le et recompilez.
Plus vous aurez l'habitude des différents messages, mieux vous comprendrez vos erreurs...
Ce n'est qu'en essayant continuellement que l'on finit par réussir....
En d'autres termes... Plus ça rate et plus on a de chances que ça marche... (Les Shadocks)
==== En debugant ====
Le bug n’est pas l’ennemi du logiciel, c’est son compagnon de route. (Loi de Derouet)
Un bon débogage est une des clefs de la réussite en informatique.
J'y consacre un [[java:debogage|tutoriel complet]].
Gardez cependant à l'esprit que:
Si vous demandez à un collègue son avis sur un bug sur lequel vous séchez depuis trois jours, il le résoudra en trois secondes (Loi du Débogueur du Bogue du Voisin).
Travailler à plusieurs n'offre pas que des inconvénients...
==== En testant ====
Un programme sans bug est un programme qui n’a pas été suffisamment testé.(Antigarantie de Boué)
L'idéal serait que quelqu'un d'autre que le programmeur écrive à l'avance le programme de test. Comme ce n'est pas toujours le cas, une bonne pratique reste quand même d'écrire à l'avance son programme de test, en le séparant le plus possible de la partie à tester.
Par exemple, en créant une classe de test extérieure au programme.
Si un programmeur teste son propre code et qu'il ne trouve pas d'erreurs, c'est qu'il n'en reste plus qu'une, au minimum.(BM)
Faites tester votre programme par d'autres que vous!