Commenter son code : le guide [Wiki GInfo]

Cette page est en lecture seule. Vous pouvez afficher le texte source, mais ne pourrez pas le modifier. Contactez votre administrateur si vous pensez qu'il s'agit d'une erreur.

====== Commenter son code : le guide ======

Bien commenter son code aide à s'y retrouver, réduit le temps passé à le maintenir, aide l'équipe de développeurs à naviguer entre les tâches et facilite la passation du projet. Il n'y a que des points positifs ! 

Pour garantir une certaine cohérence, il est préférable de suivre les mêmes conventions sur l'ensemble du projet. Cette page econstitue un résumé non exhaustif des bonnes habitudes à prendre.
 
===== Conseils généraux =====

==== Commentaires header  ====

Les commentaires //header// sont des blocs de commentaires, s'étendant donc sur plusieurs lignes, permettant de présenter un fichier source ou une fonction.

<code php>
/**
 * Le contrôleur de la page d'administration du site.
 *
 * Class AdminController
 * @Route("/admin")
 * @Security("is_granted('ROLE_ADMIN')")
 */
class AdminController extends Controller
{
    // contenu de la classe
}
</code>

Une ligne simple suffit ! Le but n'est pas d'étouffer le lecteur sous l'information.

<code php>
/**
 * Cette fonction gère l'envoi de mails de relance aux utilisateurs n'ayant pas encore signé leur(s) cotisation(s).
 *
 * @Route("/relance", name="admin_relance")
 * @Template("Admin/relance.html.twig")
 */
public function relance()
{
    // corps de la fonction
}
</code>

On peut remarquer que les noms transparents des classes, fonctions et variables explicitent déjà leur usage. 

<note tip> Un nommage efficace réduit énormément la quantité de commentaires à utiliser pour décrire le code. C'est la première chose à laquelle penser ! </note>


==== Commentaires in-line  ====

Comme leur nom l'indique, ces commentaires s'étendent généralement sur une ligne.


===== Particularités des différents langages =====

==== PHP ====



==== HTML/Twig ====



==== CSS ====



==== Javascript ====