# Programmation/Commentaires

* Historique
* Abstraction

## Concepts de base

* Commentaires
* Instructions
* Variables
* Types
* Expressions
* Comparaisons
* Instructions de contrôle
* Entrées-sorties

## Concepts spécifiques

* Manipulation de chaînes
* Procédures et fonctions
* Gestion de mémoire
* Gestion des exceptions
* Paradigmes de programmation
* Programmation séquentielle
* Programmation concurrente
* Programmation impérative
* Programmation orientée objet
* Programmation générique
* Programmation orientée aspect
* Programmation fonctionnelle
* Programmation logique
* Programmation par contrat

## Logiciels

* Eclipse
* NetBeans
* PhpStorm
* PyCharm
* SciTE
* Visual Studio Code

## Annexes

* Structure et style
* Règles de programmation
* Langages
* Historique
* Abstraction

## Concepts de base

* Commentaires
* Instructions
* Variables
* Types
* Expressions
* Comparaisons
* Instructions de contrôle
* Entrées-sorties

## Concepts spécifiques

* Manipulation de chaînes
* Procédures et fonctions
* Gestion de mémoire
* Gestion des exceptions
* Paradigmes de programmation
* Programmation séquentielle
* Programmation concurrente
* Programmation impérative
* Programmation orientée objet
* Programmation générique
* Programmation orientée aspect
* Programmation fonctionnelle
* Programmation logique
* Programmation par contrat

## Logiciels

* Eclipse
* NetBeans
* PhpStorm
* PyCharm
* SciTE
* Visual Studio Code

## Annexes

* Structure et style
* Règles de programmation
* Langages
[ Modifier le sommaire ]
Un commentaire est un texte ajouté au code source d'un programme servant à décrire le code source, facilitant sa compréhension par les humains. Il est donc séparé du reste du code grâce à une syntaxe particulière, ce qui fait qu'en général, le commentaire est ignoré par le compilateur ou l'interpréteur du langage concerné.

## Pourquoi ajouter des commentaires ?

Ajouter des commentaires à un programme permet de décrire ce que fait le code, en utilisant un langage naturel. Il est important d'ajouter des commentaires pour les raisons suivantes :

### Expliquer le rôle d'une fonction

    Utiliser une fonction est compliqué si on ne sait pas ce qu'elle fait, ce qu'elle retourne. Une explication permet de savoir comment l'utiliser.

### Expliquer le fonctionnement d'un algorithme complexe

    Le code source des algorithmes les plus complexes ne suffit pas à en comprendre le fonctionnement. Une description synthétique permet de le modifier pour l'adapter à un autre projet, ou pour le corriger en cas de problèmes.

### Justifier certains choix techniques

    Un code source est souvent repris ultérieurement (correction, réutilisation). Si certains choix ne sont pas justifiés par un commentaire explicatif, ils pourront être remis en cause par le développeur.

### Lister les contextes d'appel à une fonction

    Un commentaire expliquant quand la fonction est appelée permet de comprendre son rôle et les circonstances de déclenchement de l'appel à la fonction.
Selon Martin Fowler, l'ajout de commentaire peut aussi être le symptôme d'un code de mauvaise qualité, notamment parce qu'il ne ferait pas appel à des fonctions bien découpées et bien nommées.

## Syntaxe

La syntaxe utilisée dépend du langage de programmation, ou du format de données. Dans les exemples qui suivent, l’élément de syntaxe caractéristique du commentaire est en vert.

### Bloc de commentaire

Un bloc de commentaire commence par une séquence de caractères (en vert ci-dessous), et se termine par une autre séquence. Le commentaire peut donc s'étaler sur plusieurs lignes.
* XML, SGML, XHTML, HTML :
* CSS, C, Java, C++, C#, JavaScript, PHP :
* Pascal :
    ou

### Ligne de commentaire

Une ligne de commentaire commence par une séquence de caractères (en vert ci-dessous), et se termine implicitement à la fin de la ligne de code. Si le commentaire s'étale sur plusieurs lignes, il faut répéter la séquence au début de chaque ligne.
* Java, C++, C#, JavaScript, PHP :
* Basic, Batch (pour DOS) :
* Shell unix, PHP, Python, fichier de configuration (.ini, .cfg) :
* Fichier de configuration (.ini, .cfg) :
* Ada, ASN.1, Eiffel :

## Autre utilisation

Certains langages utilisent une syntaxe particulière de commentaires interprétée par une ligne de commande spéciale pour générer une documentation :
* Java :
La documentation générée est au format HTML, utilisant la syntaxe suivante :
* C# :
La documentation générée est au format XML, utilisant l'une des deux syntaxes suivantes :
* PHP :
La phpdoc est interprétée pour générer une documentation automatique, par les IDE pour l'autocomplétion, et par les analyseurs de code statique chargés de garantir la qualité du code. Elle se distingue des commentaires de base par l'ajout d'une deuxième étoile au début d'un commentaire de bloc, puis d'un arobase avant le mot clé :

## Références

* ↑ https://github.com/lee-dohm/code-smells#comments