Un commentaire doit fournir un contexte ou des précisions que le code seul ne peut apporter évitant une incompréhension quant aux intentions d'une méthode.
Prenons l'exemple de la méthode ci dessous et posez vous les questions suivantes : Que représente un token ? Comment est-il obtenu ? à quoi peut il servir ?
public function getOne(string $id): Token
{
return Token::retrieve($id);
}
Les réponses à ces questions resteront vaines car le code à lui seul a de grandes difficultés à exprimer clairement des intentions, aussi auto-documenté et explicite soit-il, le code demeure avant tout une série d'instructions détaillées destinées à une machine.
La qualité premiere d'une ligne de code est d'être explicite, mais sa finalité reste d'être compilé et exécuté ce qui rentrera, par moments, en conflit avec la lisibilité de ce dernier.
L'ajout d'un commentaire décrivant les intentions et le contexte de la méthode la rendra bien plus claire et explicite :
/**
* A token is immutable and represents information provided
* by a customer, such as their credit card, bank account
* or personal details.
*
* It is obtained via Stripe's API.
*/
public function getOne(string $id): Token
{
return Token::retrieve($id);
}
Grâce à ce commentaire, nous obtenons des informations sur la nature du token, sur son caractère immuable, ainsi que sur sa provenance.
L'utilisation d'une API implique généralement un service tiers avec probablement des limitations technique (authentification, disponibilité, rate limiter ...), l'immutabilité étant quant à elle synonyme de prévisibilité pour le système.
Ces informations ont énormément de sens sur le contexte d'utilisation et la finalité de la méthode et faciliteront la lecture et votre compréhension en diagonale du code.
Un bonne description
Gardez en tête qu'un commentaire reste une chose relativement bancale, évoluant à coté du code, il sera le premier à devenir obsolète et pourrait fortement induire en erreur.
Le code détient la vérité alors qu'un commentaire ment ou mentira en vieillissant.
L'ajout d'un commentaire doit uniquement contribuer à la compréhension générale du code et non à répondre à une complexité de ce dernier.
N'écrivez pas un commentaire pour éclaircir le code mais pour le contextualiser, un bon commentaire ne doit pas substituer le code mais le compléter.