====== 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.
/**
* 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.
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 !
==== 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 ====