Quelques conseils pour commenter votre code

Dans la plupart des projet Magento on ne travaille jamais seul, c’est pourquoi il est très important de toujours commenter vos classes, vos méthodes, vos variables et vos templates. Mais pas n’importe comment, voici une présentation des différentes nomenclatures à respecter dans votre programmation.

Les classes

Entêtes à placer en haut de chaque classe :

/**
 * Catalog category helper
 *
 * @category   Sample
 * @package    Sample_Catalog
 * @author    Nicolas Verhoye <nverhoye@atecna.fr>
 */
class Sample_Catalog_Helper_Category extends Mage_Catalog_Helper_Category {}

Vous noterez que tout est en anglais (bah oui sinon ce serait trop simple :)).
On précisera 4 choses :
– Le nom de la classe
– La catégorie (namespace)
– Le package (nom de module complet)
– L’auteur

Les méthodes

Voici les entêtes à placer en haut de chaque méthode :

/**
 * Retrieve category url
 *
 * @param   Mage_Catalog_Model_Category $category
 * @return  string
 */
public function getCategoryUrl($category)
{
	if ($category instanceof Mage_Catalog_Model_Category) {
		return $category->getUrl();
	}
	return Mage::getModel('catalog/category')
		->setData($category->getData())
		->getUrl();
}

On précisera 3 choses :
– Le nom de la méthode, avec pourquoi pas une description
– Les paramètres possible à passer (avec le cast)
– Le retour de la méthode (avec le cast)
Notez que sur Eclipse vous pouvez générer de manière automatique ces commentaires en vous plaçant juste avant la méthode et en tapant « /** » puis « Entrer ».
D’autre chose peuvent être précisé comme le @todo (un pense-bête pour une futur évolution de la méthode).

Les variables

Voici les entêtes à placer au dessus des variables dont vous jugez l’utilité :

/**
 * Some function
 *
 * @return void
 */
public function someFunction()
{
	/** @var $product Mage_Catalog_Model_Product */
	$product = Mage::getModel('catalog/product');
}

Pas la peine de commenter chacune des variables que vous coderez, focalisez-vous sur les essentiels.
Exemple dans notre cas nous voyons à vue d’oeil que la variable est une instance de la classe Mage_Catalog_Model_Product. De plus un simple « CTRL+CLICK » sur la variable nous amènera sur la classe en question (sur Eclipse ou Netbeans).
On précisera 3 choses :
– Le noeud @var
– Le nom de la variable
– Le cast de la variable (ou sa classe).

Les templates

Voici les entêtes à placer en haut des templates, ca reste facultatif mais c’est toujours utile de les retrouver :

<?php
/**
 * Shopping cart template
 *
 * @see Mage_Checkout_Block_Cart
 */
?>

<div class="cart"> (...) </div>

On précisera 2 choses :
– Une description du template
– La classe du Block rattaché à votre template