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.