Ce guide est accessible à pratiquement n'importe qui. La plupart des recommandations est extrêmement facile à appliquer, et ne nécessite à peu près aucune compétence en informatique.
Le problème: comme un programmeur est beaucoup plus intelligent que ce qu'on lui recommande ici, il jugera probablement superflu de se contraindre à ces recommandations… ce qui explique la plupart des lois de Murphy de l'informatique dont certaines parmi d'autres pensées agrémentent ce tuto.
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)
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:
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:
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é:
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 */
/** 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 <p>marques</p> 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<lim){ } */ return 0;// TODO à implémenter dès que possible }
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 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 Object de java:
Et 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 trucs pour éviter les ennuis…
for (int i=0;i<2;i++){ for (int i=0;i<2;i++){ } for (int i=0;i<2;i++){ System.out.... etc }
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; }
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)
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 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…
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!