Pourquoi commenter ?

Les intérêts sont multiples et variés allant du simple « j’en suis là » à la fin de la journée jusqu’à la documentation d’une application.

Commenter pour comprendre ce qu’on a fait

Lors d’une session de développement on est souvent confronté à un problème nouveau à gérer et la solution n’est pas forcément toujours évidente. On fait quelques recherches, on trouve une solution ou l’inspiration pour la créer et on l’intègre. Tout fonctionne, c’est parfait, on est content.
3 mois plus tard on doit revenir dessus car il faut améliorer la fonction en y intégrant de nouveaux paramètres ou s’en resservir pour un autre projet, et là c’est le drame : on ne comprend plus comment ça fonctionne, voire même à quoi sert ladite fonction… Les 30 secondes nécessaires à écrire les quelques commentaires salutaires nous auraient permises d’éviter une décapilarisation crânienne subite et la perte de pas mal de temps.

Commenter pour expliquer aux autres

On peut travailler en équipe sur un projet et d’autres développeurs risquent d’avoir à intervenir sur votre code pendant que vous faites autre chose. Autre cas de figure : vous développez seul un projet puis un peu plus tard c’est un autre développeur qui le reprend ou qui vous rejoin dessus. Vous pouvez également être en train de développer un script/module/librairie/application destiné(e) à être partagé(e) avec d’autres (dans le cadre d’open source par exemple).
Encore une fois, le temps passé à commenter le code évitera aux autres d’être complètement perdus à la lecture de votre chef d’oeuvre. Ceci est d’autant plus vrai que chaque développeur a son style et sa manière de coder et qui, bien souvent, n’est limpide que pour lui-même…

Commenter pour se faciliter la tâche

Les IDE de qualité sont capable de lire les commentaires DocBlock et de s’en servir pour afficher, lors de la saisie, les informations d’utilisation que vous avez pris le soin d’entrer. Dans le cadre du développement d’une application répartie en plusieurs fichiers (souvent le cas en POO ou en utilisant un framework), les commentaires révèlent toute leur puissance en vous évitant de replonger dans le code d’une fonction pour retrouver quels arguments lui passer ou encore ce qu’elle retourne.
Ce type de commentaire peut aussi être utilisé pour l’écriture automatique de la documentation d’une API, par exemple, à l’aide d’un générateur de documentation tel que PHPdocumentor ou Doxygen

Les différents types de commentaires

Il existe 3 types de commentaires : ligne simple, multiligne et DocBlock. Les 2 premiers ne servent qu’à indiquer des informations courtes au sein même du code alors que le DocBlock permettra aux IDE et générateurs de documentation d’en faire bien plus.

Les commentaires simples et multilignes se présentent de la manière suivante :

// je suis un commentaire sur une seule ligne
/* je suis
un commentaire
sur plusieurs lignes */

Le commentaire DocBlock se présente ainsi :

/**
 * Cette fonction sert à faire ceci...
 * un commentaire
 * sur plusieurs lignes
 *
 * @param string $text Description du paramètre
 * @param int $id Description du paramètre
 * @return bool Description de ce que retourne (ou non) la fonction
*/

Notez l’utilisation de certains mots clés (@param, @return) dont vous trouverez la liste complète ici. C’est précisément ces mots-clés qui permettrons à l’IDE et au générateur de documentation de travailler.

Un exemple d’utilisation

Voici un petit exemple d’utilisation des 3 types de commentaires dans un modèle du framework CodeIgniter :

<?php

class Blog_model extends CI_Model {

	// constructeur
	function __construct() {
		parent::__construct();
	}

	/**
	 * Recupération des derniers posts de wordpress
	 *
	 * @param	int $count	Le nombre de posts que l'on veut afficher (optionnel)
	 * @return	object		Les posts à afficher
	 */
	function get_latest_posts($count = 5) {
		// requete mysql à l'aide d'ActiveRecord
		$this->db->select('post_title, post_name');
		$this->db->where('post_status', 'publish');
		$this->db->where('post_type', 'post');
		$this->db->limit($count);
		$this->db->order_by('ID', 'desc');

		$query = $this->db->get('wp_posts');
		
		/* on récupère les posts
		sous forme d'objet */
		$data = $query->result();

		//var_dump($data); exit; // test des résultats obtenus
		
		// renvoi des résultats au controlleur
		return $data;
	}

}

J’ai eu la main un peu lourde ici mais en même temps il vaut mieux trop de commentaires que pas assez !

Conclusion

Il y a peu de temps j’ai eu l’occasion d’intervenir sur un gros projet de CRM/ERP qui était quasiment abouti et dont le développeur a du se retirer. Malheureusement il n’avait pas jugé utile de commenter son code et la conséquence directe à été une grosse perte de temps pour moi (le temps de comprendre le fonctionnement) et une grosse perte de temps et d’argent pour le client car il a du supporter le coût de « temps de compréhension » du code existant en plus du temps de développement nécessaire au résultat demandé…
Pour faire bref, passez un peu de temps à commenter votre code – votre client, les utilisateurs de votre code et vous-même ne vous remercieront jamais assez !

J’ai trouvé cette astuce, en cherchant un peu partout une solution à ce problème, sur ce blog. Je me suis simplement permis de traduire en partie sa mise en place.

Autocomplete de base

Pour accéder à l’autocomplete des fonctions de base de CodeIgniter, il suffit simplement de créer un fichier « nom_du_fichier.php » dans le dossier de projet de Netbeans (nbproject) de votre application et d’y coller le contenu ci-dessous. Après cela, relancez Netbeans. Pour ce tutorial nous supposerons que ce fichier sera nommé « ci_autocomplete.php ».

<?php

/**
* @property CI_DB_active_record $db
* @property CI_DB_forge $dbforge
* @property CI_Benchmark $benchmark
* @property CI_Calendar $calendar
* @property CI_Cart $cart
* @property CI_Config $config
* @property CI_Controller $controller
* @property CI_Email $email
* @property CI_Encrypt $encrypt
* @property CI_Exceptions $exceptions
* @property CI_Form_validation $form_validation
* @property CI_Ftp $ftp
* @property CI_Hooks $hooks
* @property CI_Image_lib $image_lib
* @property CI_Input $input
* @property CI_Language $language
* @property CI_Loader $load
* @property CI_Log $log
* @property CI_Model $model
* @property CI_Output $output
* @property CI_Pagination $pagination
* @property CI_Parser $parser
* @property CI_Profiler $profiler
* @property CI_Router $router
* @property CI_Session $session
* @property CI_Sha1 $sha1
* @property CI_Table $table
* @property CI_Trackback $trackback
* @property CI_Typography $typography
* @property CI_Unit_test $unit_test
* @property CI_Upload $upload
* @property CI_URI $uri
* @property CI_User_agent $user_agent
* @property CI_Validation $validation
* @property CI_Xmlrpc $xmlrpc
* @property CI_Xmlrpcs $xmlrpcs
* @property CI_Zip $zip
*/

class Controller {};

/**
* @property CI_DB_active_record $db
* @property CI_DB_forge $dbforge
* @property CI_Config $config
* @property CI_Loader $load
* @property CI_Session $session
*/

class Model {};

?>

Comment ça fonctionne ?

Au lancement de Netbeans, celui-ci lit les fichiers contenus dans le répertoire nbproject (notamment project.xml et project.properties) afin de préparer l’environnement de développement.
En « lisant » le fichier ci_autocomplete.php il repère les propriétés définies dans le DocBlock pour les classes Controller et Model.
C’est cela qui lui permettra de fournir l’autocomplete lors de l’édition d’un controlleur ou d’un modèle. En parcourant le contenu du fichier on remarquera que l’on liste simplement les classes mises à disposition par CodeIgniter.

Ajoutez vos propres classes

Le but de la manoeuvre étant aussi d’accéder à l’autocomplete sur vos modèles et librairies, il suffit d’éditer le fichier ci_autocomplete.php que vous venez de créer pour les y incorporer :

* @property Nom_de_votre_classe $nom_de_votre_objet

Par exemple, en ajoutant

* @property Portfolio_model $portfolio_model

dans le DocBlock Controller, vous aurez accès aux méthodes du modèle Portfolio_model lors de l’édition d’un controlleur :

Note : pour que toutes les fonctions de vos modèles soient également disponibles pendant l’édition d’un modèle, il faudra également ajouter les modèles dans le DocBlock du modèle.

Conclusion

Il est dommage que, par défaut, on ne puisse pas accéder à l’autocomplete des fonctions de CodeIgniter — ceci étant apparemment dû à la manière dont le code est commenté — mais grâce à cette petite astuce tout rentre dans l’ordre.
Dernier petit conseil : utilisez également les commentaires DocBlock avec vos méthodes de modèles pour facilement en afficher l’utilisation lors de l’édition de controlleurs et modèles.