02: Pas de commentaires ? C'est inacceptable !

Introduction

En utilisant des noms de variables sensiblement différents, et intelligibles, nous pouvons rendre notre code plus compréhensible, que ce ce soit pour une relecture (pour nous), ou bien une relecture par les autres (dans le cas de logiciels libres par exemple) [1].

//[1]
float imageLargeur, imageLongueur, imageAire;
imageLargeur = 8.0;
imageLongueur = 4.5;
imageAire = imageLargeur * imageLongueur;

Jusqu'ici nos bouts de codes ne font que quelques lignes, mais même des programmes assez simples peuvent comporter des centaines de lignes de code. Quand vous relisez votre code après quelques semaines, ou quelques mois, il peut être difficile de se rappeler comment vous avez décidé de programmer, et quels moyens vous utilisez pour y parvenir. C'est là que les commentaires rentrent en jeu. Les commentaires vous aident à savoir ce qu'une partie de votre code fait et pourquoi c'est cette solution que vous avez choisi. Certains programmeurs vont si loin qu'ils commentent même leur classes, ce qui les aident à organiser leur idée, et leur évite de tomber dans une impasse.

Il est conseillé de commenter son code. Nous pouvons vous assurer que c'est un investissement rentable, qui vous rendra service plus tard. Aussi, si vous partagez votre code avec d'autres personnes, vos commentaires les aideront à adapter à leurs propres besoins votre programme.

Réaliser un commentaire

Pour commencer un commentaires, alignez deux slashes à la suite, tout ce qui suivra dans la ligne de votre code, sera considéré comme un commentaire.

// Ceci est un commentaire.

Dans Xcode les commentaires sont en vert. Si un commentaire doit s'étaler sur plusieurs lignes (par exemple dans l'en-tête de présentation de votre code source), il vaut mieux utiliser cette méthode : /* Votre commentaire */.

/* Ceci est un commentaire
écrit sur plusieurs lignes. */

« Outcommenting »

Nous vous expliquerons comment débugger un programme facilement — grâce à Xcode — plus longuement dans un autre chapitre. Cependant, une façon à « l'ancienne » de débugger un programme est de commenter des parties de code, afin de savoir quelle est la partie qui fonctionne mal. Via les /* */, désactiver certaines parties du code, pour voir si le reste tourne comme prévu. Cela vous permet de faire la chasse aux bugs. Si la partie commentée devait, par exemple, retourner une valeur, vous pouvez inclure une ligne temporaire où vous affectez à la variable une autre valeur particulière pour tester la bonne marche de votre programme.

Pourquoi commenter ?

L'importance des commentaires ne doit pas être sous-estimée. C'est souvent utile d'apposer une explication en bon français sur ce que fait une longue série de commandes. C'est parce que de cette façon, vous n'aurez pas à déduire du code, ce qu'il fait. C'est le commentaire lui même qui le rappellera immédiatement. Vous devriez aussi utiliser les commentaires pour souligner les parties difficiles, ou impossible à déduire à partir du code. Par exemple, si vous programmez une fonction mathémathique utilisant un modèle spécifique décrit en détail dans un livre, vous souhaiterez surement mettre une référence bibliographique.

Quelques fois il peut être utile d'écrire un commentaire avant de coder. Cela vous aidera à structure vos pensées et programmer sera plus simple.

Les lignes de code contenues dans ce livre ne contiennent pas beaucoup de commentaires, car elles sont longuement expliqué après chaque partie de code.