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:

1. Règle d'or: adoptez UN style et conservez-le tant que vous le pourrez;
2. Si vous devez changer de style (compromis en projet par exemple), veillez à le définir très clairement par écrit;
3. Indentez votre code avec des tabulations, pas des espaces;
4. L'indentation de votre programme doit permettre d'en comprendre la structure;
5. Définissez la longueur maximale de ligne (en général 80 ou 120 caractères, vous pouvez le régler dans la plupart des éditeurs).

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);
• Incompréhensible (ou illisible);
• Non Utilisable (par d'autre, ou par soi-même d'ailleurs, cf. infra);
• Totalement Sté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 <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).

• La syntaxe recommandée par sun/oracle
• Checkstyle: Un outil pour vérifier automatique son style

Quelques trucs pour éviter les ennuis…

1. utilisez des noms de classe/variables/méthodes PARLANT…
2. … et dans l'idéal en anglais!
3. 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.);
4. initialisez TOUJOURS un attribut, une variable… soit lors de sa déclaration, soit par l'intermédiaire du constructeur pour les attributs.
5. … ou faites-le systématiquement dans le constructeur;
6. 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
   }

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

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

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!