Exemples de lignes de code correctement commentées
Comment
Les commentaires dans le code source sont des annotations qui permettent d’ajouter des explications, des informations supplémentaires ou des remarques sur le code, afin de faciliter la compréhension pour les développeurs. Ils sont écrits en langage naturel et ne sont pas exécutés lors de l’exécution du programme.
Pour commenter une ligne de code, il suffit d’ajouter « // » devant la ligne dans les langages de programmation comme Python, Java et Smalltalk [1]. Par exemple :
// Ceci est un commentaire en Python
print("Hello World!") // Ceci est une instruction d'affichage
En HTML, les commentaires sont déclarés en utilisant les balises <!--
et -->
[2]. Par exemple :
<!-- Ceci est un commentaire en HTML -->
<p>Ceci est un paragraphe.</p>
Exemple de commentaires pour déboguer HTML
Les commentaires sont également utiles pour le débogage du code HTML, car vous pouvez commenter des lignes de code une par une pour rechercher des erreurs [3]. Par exemple :
<!--<div class="container">
<h1>Titre</h1>
<p>Contenu</p>
</div>-->
Pourquoi
Les commentaires aident les développeurs à comprendre et à interpréter plus facilement le code. Ils permettent d’indiquer l’intention du code, de documenter les fonctionnalités, d’expliquer les algorithmes complexes et de fournir des informations utiles [2].
Quand
Les commentaires doivent être utilisés dès la rédaction du code source. Ils aident à maintenir et à améliorer la lisibilité du code au fil du temps, surtout lorsque d’autres développeurs travaillent sur le même projet ou lors de la maintenance du code existant. Il est préférable de commenter régulièrement les sections complexes ou critiques du code pour éviter des problèmes futurs [2].
Où
Les commentaires peuvent être ajoutés à n’importe quelle ligne de code ou à n’importe quelle partie du programme où une explication est nécessaire. Ils peuvent être placés avant une ligne de code, sur la même ligne ou même après la ligne de code. Dans les langages de programmation, ils sont généralement ajoutés à la fin de la ligne de code en utilisant le symbole approprié [1].
Qui fait quoi, pourquoi, comment
Les développeurs doivent commenter leur propre code pour expliquer leur logique, leur approche et les décisions de conception prises. Les commentaires aident également les autres développeurs qui travaillent sur le même code à comprendre les fonctionnalités, à résoudre les problèmes et à maintenir le code [2].
Exemples de lignes de code correctement commentées
// Ce code en Python calcule la somme de deux nombres
def addition(a, b):
# Ajouter les deux nombres et retourner le résultat
return a + b
# Exemple d'utilisation de la fonction addition
result = addition(5, 10) # Appel de la fonction avec les valeurs 5 et 10
print("Le résultat est", result) # Affichage du résultat
<!-- Ce code HTML affiche une image -->
<img src="image.jpg" alt="Image" />
<!-- Fin du code HTML -->
Sources:
- [1] How to identify class comment types A multi-language study. La date de consultation : 2023-09-01.
- [2] HTML Comments: How to Use Them. La date de consultation : 2023-09-01.
- [3] HTML Comments Example. La date de consultation : 2023-09-01.