Sujet: Truc de la semaine : techniques de commentaires

Résumé:
Le conseil de la semaine pour le 12 Février 2004, discute des avantages d'avoir une bonne technique de commentaires pour faciliter la maintenance des sites Web ainsi que pour le debugage.

Description:
Une bonne technique de commentaires rend les code LDML et HTML plus facile à lire, à comprendre et à débuguer. Lasso fournit plusieurs manières différentes qui s'adapterons aux différents besoins de commentaires. Ce document vous fournit une vue des principes de commentaires, discute des basiques sur la manière d'écrire vos commentaires et enfin, inclut des exemples montrant comment du code a été commenté.

Principes

Les basiques des principes de commentaires tournent tous autour du moyen de les rendre les plus utiles possibles lorsque vous serez amené à revisiter votre page web plus tard. Si vous suivez ces principes votre site sera plus facile à maintenir et à débuguer.

- Ecrivez vos commentaires pour quelqu'un de non-familier avec ce site. Si votre site doit être modifié ou corrigé par quelqu'un d'autre que vous, les commentaires seront sa meilleure aide pour qu'il sache comment il fonctionne. Ecrivez donc vos commentaire de manière à en faciliter cette tâche. Après plusieurs mois, le site peut vous paraitre non-familier et ces commentaires vous rendront votre travail plus simple.

- Commentez chaque nouvelle variable, custom tag, include ou sous-routine. Une brève note en début de chaque bloc de code sera plus simple qu'un commentaire mis à droite de chaque ligne de code lorsque vous rencontrez des problèmes avec ce dernier.

- Commentez chaque constante, valeur par défaut, comparaison. Il est souvent difficile de se remémorer pourquoi telle valeur par défaut a été assignée à une variable ou dans quel intervalle de données la valeur d'une variable peut se trouver. Si une variable prend un nombre par défaut, notez-le dans un commentaire. Si une comparaison vérifie par exemple si une variable est supérieure à zéro, notez pourquoi dans un commentaire. Si une variable doit être supérieure à une autre, notez en la raison dans un commentaire.

- Incluez des liens vers la documentation. Si vous implémentez un protocole particulier ou utilisez des outils tiers, notez l'URL d'où proviennent ces codes de manière à les retrouver. Utiliser l'URL sera beaucoup plus facile que de la retrouver à travers un moteur de recherche.

- Ecrivez du code "auto-commenté". Si le nom de vos variables ou de vos custom tags sont suffisamment descriptifs, il ne sera pas nécessaire d'ajouter des commentaires supplémentaires. Par exemple, une variable nommé "client_prenom" est suffisamment explicite par rapport à une variable nommée "clpr".

- Ne "sur-commentez" pas. Les commentaires sont fait pour préciser pourquoi un code a été écrit ainsi plutôt que de décrire ce qu'il fait. Si vous commentez de trop votre code, vous trouverez rapidement difficile de commenter et d'écrire votre code. Une courte description de chaque bloc de code est souvent meilleure que des commentaires obscurs à la fin de chaque ligne.

- Faites des commentaires privés. Les commentaires dans LassoScript ainsi que dans les balises [Output_None] ... [/Output_None] ne seront pas transmis sur le navigateur du client web. Ces commentaires privés ne peuvent être consultés que lorsque le fichier source est édité sur le serveur. Les commentaires publics en HTML <!-- ... --> ne devraient être utilisés lorsque ces informations sont destinées à être lues par un client consultant sa page via un navigateur web. L'utilisation des commentaires privés accélèrera le chargement de la page dans les navigateurs et évitera le chargement de données inutiles pour les visiteurs du site.

Les basiques

Le tableau ci-dessous inclut chacune des méthodes de commentaires utilisées dans Lasso et en HTML. Chaque méthode affiche le début et la fin de la chaîne de caractères, le contexte dans laquelle elle peut être utilisée, des notes sur sa visibilité ou non sur le site client et si le code LDML mis à l'intérieur des commentaires est interprété par Lasso ou pas.

LassoScript
// ... fin de la ligne
Ligne simple. Les balises LDML ne sont pas interprétées. Invisibles sur le site client. Utilisé aussi pour JavaScript.

LassoScript
/* ... */
Multi-lignes. Les balises LDML ne sont pas interprétées. Invisibles sur le site client. Utilisé aussi pour JavaScript.

HTML

Les balises LDML ne sont pas interprétées. Invisibles sur le site client.

LDML
[HTML_Comment] ... [/HTML_Comment]
Les balises LDML sont interprétées par Lasso. Visible sur le site client. Ces balises génèrent des balises HTML .

LDML
[Output_None] ... [/Output_None]
Les balises LDML sont interprétées par Lasso. Invisibles sur le site client.

LDML
[Output_None][NoProcess] ... [/NoProcess][/Output_None]
Les balises LDML ne sont pas interprétées. Invisibles sur le site client.

Note - En général les commentaires ne peuvent pas être imbriqués. Si vous écrivez <!-- Commentaire <!-- Commentaire inclut --> Externe --> le premier --> rencontré arrêtera le commentaire donc le résultat affiché sera Externe -->. D'une façon similaire /* ... */ et les différentes balises de commentaires LDML ne doivent pas êtres imbriquées dans d'autres commentaires.

Exemples

LassoScript - Utilisez un bloc de commentaires pour décrire ce que LassoScript réalise. C'est également une bonne place pour garder la trace de vos modifications sur un fichier ou d'inclure une notice de copyright.

<?LassoScript
   /*
    * Fichier: header.lasso
    * Date: 2/12/2004
    * Auteur: John Doe
    *
    * Fichier en-tête inclut
    * sur toutes pages du site
    */
   
    ...

?>

LassoScript - Commentaire de chaque variable créée.

<?LassoScript
   var: 'maxrecords' = 50;
     // Nombre par défaut d'enregistrements à afficher
    
   var: 'action' = (action_param: 'action');
     // URL de la page d'action suivante
  
   ...
  
?>

LassoScript - Commentaire en début et en fin d'une évaluation conditionnelle. Particulièrement sur de longues évaluations, il peut être utile d'avoir un commentaire rappelant à quelle évaluation telle balise fermante se rapporte.

<?LassoScript
   if: ($first_name->(beginswith: 'j'));
     // Evaluation spéciale pour les noms commençant par J
   
     ...
 
  else;
     // Process pour les noms différents de J...
   
    ...
    
   /if;
     // Fin d'évaluation sur les noms en J
?>

HTML - Reporter des informations de débuggage dans des commentaires HTML. Ce type de commentaires sera visible dans le source HTML délivré sur le site client et donc visible de tout internaute. Aucune information sensible ne doit y être reportée, mais pour vos opérations de débuggage il peut être utile d'adopter cette solution pour les rendre visible de vous en tant que développeur.

[HTML_Comment]
   [Error_CurrentError: -ErrorCode]
   [Error_CurrentError]
   [Found_Count]
   [Shown_Count] ([Shown_First] - [Shown_Last])
[/HTML_Comment]

LDML - Utilisation de la balise [Output_None] pour procéder le code et inclure des commentaires sans en afficher le contenu aux visiteurs du site web. Le bloc de code suivant ne produit aucun affichage mais toutes les balises qui s'y trouvent sont procédées par Lasso.

[Output_None]
   Envoit un email à l'administrateur
   que les stats ont été mises à jour
   [Email_Send:
     -To='admin@example.com',
     -Subject='Stats Updated',
     ...]
[/Output_None]

LDML - Utilisation des balises [Output_None] et [NoProcess] pour inclure des commentaires comprennant des crochets que vous ne voulez pas voir processés par Lasso. Ceci est également un bon moyen de cacher une portion de code que vous ne souhaitez pas voir procédée par Lasso mais que vous ne souhaitez pas supprimer pour le moment.

[Output_None][NoProcess]
   NOTE - TEMPORAIREMENT SUSPENDU
   EN ATTENTE DE L'ADRESSE DE L'ADMIN
   [Email_Send:
     -To='admin@example.com',
     -Subject='Stats Updated',
     ...]
[/NoProcess][/Output_None]