Forum d'entraide PHPFrance

Bonjour à tous

Bon, j'imagine que ce n'est pas le première fois (ni la dernière sûrement ) qu'un débutant se pose de questions sur les commentaires, mais je voudrais juste savoir s'il y a, en la matière, une manière "officielle" ou "standard", voire "normalisée" pour commenter les codes !?

Je suis tombé cette aprème sur un script où les commentaires des fonctions sont vraiment bien faits, voici un petit exemple :

/**
 * create_truc()
 * 
 * Crée le fichier de "trucs" pour le mois et l'année donnés
 * 
 * @param	array		$listdata		Données de la liste concernée
 * @param	integer		$month		Chiffre du mois
 * @param	integer		$year		Chiffre de l'année
 * 
 * @return	boolean
 */
function create_truc($listdata, $month, $year)
{

Je me demandais alors si tous les développeurs chévronnés avaient l'habitude de commenter de la même manière leurs codes ou si chaqu'un avait ses propres "manies" ?

Sinon, existe-t-il des recommandations "officielles" pour les commentaires ?

Merci à tous pour vos retours d'expérience...

PS. bon, j'ai un peu modifié le nom de la fonction, bien que ce soit un script du domaine public, je ne voudrais pas froisser l'auteur du script en publiant un bout de son code sans autorisation.

Sinon, existe-t-il des recommandations "officielles" pour les commentaires ?

N'étant pas passé par une école d'informatique je ne saurai pas te répondre à ce sujet.

Mais concernant les commentaires en général il faut en mettre plutôt plus que moins. Le principe est d'en mettre suffisamment pour que tu puisses retrouver facilement le fonctionnement de ton code dans 6 mois, quand tu auras tout oublié.

Fais comme si tu travaillais dans une équipe. Ton code doit être facilement compréhensible par un autre membre de l'équipe qui ne connait pas ton code. C'est une bonne manière de procéder même pour un développeur solo.

Bonjour,

En effet, il existe une certaine normalisation au niveau des commentaires qui est issue du monde Java.
Ainsi on parle souvent de commentaire style "Javadoc", javadoc étant un outil java qui permet de générer automatiquement la documentation d'une application grâce aux commentaires que le développeur aura mis dans son code.

+ d'infos ici:
http://fr.wikipedia.org/wiki/Javadoc
http://java.sun.com/j2se/javadoc/ (site officiel, un peu rébarbatif)


A noter qu'il existe des équivalent de Javadoc pour PHP, les plus connus étant:
- PHPdoc: http://www.phpdoc.org
- Docxygen: http://www.stack.nl/~dimitri/doxygen/
- Il existe aussi AutoPhpDoc de Naholyr mais son site hébergé chez Free semble down à l'heure actuelle...

Merci AB et @rthur pour vos réponses

AB, perso j'inscrivais mes commentaires dans le but de pouvoir relire et comprendre mon code entre deux phase de travail, qui peuvent être espacées parfois de quelques mois... mais ton conseil de faire comme si je travaillais dans une équipe me semble tout-à-fait intéressante, en effet, j'avais tendance à mettre parfois des abréviations batardes ou des bouts d'explications que seul moi pouvait comprendre (et encore, il m'est arrivé de ne pas comprendre le sens de certaines annotations )...

Donc, je vais suivre ton conseil désormais, et rédiger mes commentaires de sorte que d'autres puissent aussi me comprendre, ça me paraît une bonne idée, même si, fatalement, ça implique plus de boulot...

@rthur, merci beaucoup pour les infos et les liens, qui m'ont permis de comprendre la raison de certaines balises utilisées dans le petit bout de code d'exemple que j'ai présenté dans le premier message... de plus, l'idée de pouvoir générer une documentation automatiquement, même sommaire, directement à partir des codes sources, me paraît vraiment excellente, je vais voir si je peux m'en servir à l'avenir...

Merci pour vos éclairages, très instructifs... à+

Modération :
FredoMkb, si ta question est résolue, pense à ajouter le tag [Résolu]

Ha oui, désolé, j'oublie tout le temps... merci de me l'avoir rappelé