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.

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

/**
 * 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
}

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

/**
 * 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
}

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

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