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