Les commentaires en R : commenter son code (et désactiver des blocs)

Le symbole

Un commentaire en R commence par #. De ce caractère jusqu'à la fin de la ligne, R ignore tout :

# This whole line is a comment. R skips it.
speed_kmh <- 90

speed_ms <- speed_kmh / 3.6  # convert to meters per second

print(speed_ms)

Les deux placements sont légaux : un commentaire sur sa propre ligne, ou un commentaire en fin de ligne après du code. Il n'y a rien à fermer - le commentaire s'arrête simplement là où la ligne s'arrête. Un seul # suffit, et un # à l'intérieur d'une chaîne entre guillemets n'est qu'un caractère, pas un commentaire :

tag <- "#1 fan"  # the first # is data, this one is a comment
print(tag)

R n'a pas de commentaire multiligne

Voici la réponse à la question que chaque débutant R finit par googler : R n'a pas de syntaxe de commentaire de bloc. Il n'y a pas de /* ... */, pas de """docstring""", pas de =begin/=end. Chaque ligne commentée a besoin de son propre #. C'est une simplicité délibérée du langage - et c'est moins pénible qu'il n'y paraît, car l'outillage comble le manque.

La solution du monde réel : le raccourci de bascule de votre éditeur. Dans RStudio, sélectionnez les lignes et appuyez sur Ctrl+Shift+C (Windows/Linux) ou Cmd+Shift+C (macOS). Chaque ligne sélectionnée reçoit un préfixe # ; appuyez à nouveau et ils disparaissent. C'est ce que font réellement les programmeurs R, des dizaines de fois par jour, et cela vaut la peine de l'ancrer dans votre mémoire musculaire dès cette semaine. VS Code, Vim et Emacs ont tous des commandes équivalentes de bascule de commentaire pour les fichiers R.

L'astuce if (FALSE). Parce que FALSE n'est jamais vrai, envelopper du code dans if (FALSE) { ... } garantit qu'il ne s'exécute jamais :

if (FALSE) {
    expensive_call <- 1 / 0
    cat("you will never see this\n")
}

cat("but you will see this\n")

Connaissez-la, mais traitez-la comme une curiosité plutôt qu'une habitude, car elle a de vraies réserves. Le code sauté doit rester du R syntaxiquement valide - un véritable commentaire de bloc peut contenir n'importe quoi, mais un if (FALSE) autour d'une ligne à moitié écrite est une erreur de parsing qui arrête tout le script. Il change aussi silencieusement de sens si les accolades sont modifiées. Quand vous voulez désactiver des lignes, le raccourci de l'éditeur est plus sûr ; quand vous les voulez disparues, supprimez-les - c'est à ça que sert le contrôle de version.

Ce que disent les bons commentaires : le pourquoi, pas le quoi

Le code dit déjà ce qu'il fait. Un commentaire qui le répète est du bruit qui finira par se périmer et par mentir :

# Bad: narrates the obvious
x <- x + 1  # add 1 to x

# Good: explains the reason
x <- x + 1  # customer-facing IDs are 1-based, data is 0-based

Le second commentaire porte une information que le code ne peut pas porter : pourquoi l'incrément existe. C'est le test de chaque commentaire que vous écrivez - explique-t-il une intention, un contexte ou une décision non évidente ? Les commentaires gagnent leur place sur les lignes bizarres : le contournement d'un bug de package, le décalage d'un qui est intentionnel, la formule tirée d'un article précis. Et souvenez-vous de la règle de maintenance : quand vous changez le code, changez son commentaire, car un commentaire faux est pire que pas de commentaire du tout.

Si vous vous surprenez à écrire un commentaire pour expliquer ce que contient une variable, la meilleure correction est souvent un nom plus clair - voir variables pour cet argument.

Des en-têtes de section repliables dans RStudio

Les scripts d'analyse s'allongent, et les commentaires font office de table des matières. RStudio traite une ligne de commentaire se terminant par quatre - ou plus (ou = ou #) comme un en-tête de section :

# Load data ----------------------------------------------------------

# Clean and reshape ----

# Model ====

Chaque section devient repliable et apparaît dans le plan du document de RStudio, si bien qu'un script de 300 lignes se transforme en liste navigable d'étapes : charger, nettoyer, modéliser, tracer. N'importe lequel des caractères de fin fonctionne du moment qu'il y en a au moins quatre ; choisissez un style et restez cohérent. Même hors de RStudio, les commentaires d'en-tête de section rendent la structure d'un script visible d'un coup d'œil - c'est la documentation la moins chère qu'une analyse puisse avoir.

Les commentaires roxygen2 : #' dans la nature

En lisant le code R des autres - surtout les sources de packages - vous rencontrerez des commentaires commençant par #' :

#' Convert a speed from km/h to m/s
#'
#' @param kmh Speed in kilometers per hour.
#' @return Speed in meters per second.
kmh_to_ms <- function(kmh) {
    kmh / 3.6
}

Ce sont des commentaires de documentation roxygen2. Écrits juste au-dessus d'une définition de fonction, ils sont compilés par l'outillage des packages en pages d'aide formelles, celles que vous lisez avec ?function_name. Les balises (@param, @return) décrivent les entrées et la sortie de la fonction. Pour R lui-même, une ligne #' est un commentaire ordinaire - la convention n'a de pouvoir que dans la chaîne d'outils de développement de packages. Vous n'aurez pas besoin d'en écrire avant de construire un package ou de documenter sérieusement vos propres fonctions ; pour l'instant, sachez juste les reconnaître pour que le code source des packages ne paraisse pas mystérieux.

Ce qu'il faut retenir

• # commence un commentaire ; il court jusqu'à la fin de la ligne, que la ligne soit tout commentaire ou code-puis-commentaire.
• R n'a pas de commentaire multiligne - basculez les blocs avec Ctrl/Cmd+Shift+C dans RStudio, et réservez if (FALSE) {} au code syntaxiquement valide que vous sautez rarement.
• Commentez le pourquoi, pas le quoi - et mettez les commentaires à jour quand le code change.
• Les commentaires # Section name ---- donnent à RStudio des sections repliables et aux lecteurs une carte du script.
• Les lignes #' sont des commentaires de documentation roxygen2 qui deviennent les pages d'aide des packages.

Prochaine étape : les variables - les créer avec <-, bien les nommer, et comment R traite les valeurs qu'elles contiennent.