Spécification de développement pour les codes du projet "le_terrier"

André Connes, andre.connes@toulouse.iufm.fr

David Lucardi

 

v 0.1 6 mai 2002
v 0.2 29 décembre 2002

Ce document essaye de préciser les contraintes que nous souhaitons respecter lors de l'écriture (et/ou modification) de fichiers Tcl/Tk afin d'assurer une meilleure maintenance et lisibilité du code produit.

1. Introduction

Il ne s'agit pas de contraintes dans le but d'ennuyer le développeur bénévole.

Il s'agit de respecter quelques règles simples qui, dans le passé, ont permis une relecture aisée du code produit.

Car une application naît, vit par la volonté de différents développeurs.

Mais elle meurt si elle est illisible.

Enfin, la lisibilité est source d'apprentissage.

Développer un programme c'est écrire du code avec l'intention de communiquer avec des personnes plutôt qu'avec des machines !

2. Documentation du code à l'aide de commentaires

Les commentaires donnent des indications au lecteur mais sont ignorées du calculateur (sauf si ce sont des directives pour l'interpréteur).

Bien documenter le code par des commentaires est difficile mais c'est une nécessité.

Commentons sans excès, mais commentons, les parties difficiles à comprendre.

Evitons les commentaires 

  set i [expr $i - 1] ;# passer à l'élément suivant

  set i [expr $i + 1] ;# ajouter 1 à la variable i

Préférons donc 

  set i [expr $i + 1] ;# passer à l'individu suivant

encore mieux 

  incr $i ;# passer à l'individu suivant

3. Identifieur

Tout programme contient deux sortes de symboles : les premiers appartiennent au langage, les seconds sont les identifieurs.

Les premiers peuvent être un caractère spécial ou une paire de caractères comme 

  + - ! == != > < { } [ ] # ;# etc.

ou un mot réservé comme 

  if else elsif while proc etc.

Les identifieurs peuvent être des identifieurs standard comme 

  puts gets set pack frame etc.

ou des identifieurs définis par l'utilisateur.

Le choix des identifieurs définis par l'utilisateur est fondamental : un bon choix rend le programme plus facile à lire, à comprendre, à modifier, à corriger. Un identifieur long n'est pas nécessairement le meilleur. Si un identifieur n'est utilisé que peu de fois, dans une partie réduite du programme, une lettre peut être un bon identifieur, mais une lettre ne sera pas un bon choix pour un identifieur utlisé fréquemment dans différentes parties du programme. 

  noPage numPage

sont des identifieurs plus compréhensibles que NP ou XXX pour désigner un numéro de page. 

  pi

est surement mieux que A pour désigner le nombre 3,141592...

4. Littéral et constante

60, 3.141592 et "fin" sont des littéraux. Nous pouvons nommer les littéraux. Un littéral nommé est une constante.

Après les instructions : 

set maxLignes 60
set pi 3.141592
set consigneFin fin

nous pouvons écrire : 

for { i = 0; $i <= $MaxLignes; incr $i } {
    faire un traitement
    sur la ligne numéro i
}
set circonference [expr 2 * $pi * $r]
while { $consigne != $consigneFin } {
    quelque chose à faire
}

L'utilisation des constantes rend le programme plus facile à lire, à comprendre, à modifier, à corriger.

5. Variable

Les indications concernant les constantes s'appliquent aux variables d'autant plus que TclTk ne fait pas de différence entre les deux ! Il n'existe pas de constante en TclTk mais l'utilisateur doit faire comme si afin d'améliorer le code écrit.

Evitons 

   a, i, n, a20, n7, toto, zorro, etc.

Peu de temps après l'écriture d'un code utilisant de telles variables, nous ne saurons plus à quoi elles peuvent bien servir.

6. Indentation du code

La règle générale est la suivante :

##########################################

A développer

condition boucle fonction etc.

voir Brent B.Welch pour des exemples de code

##########################################

7. En-tête GPL pour le code

Par exemple : 

#*************************************************************************
#  Copyright (C) 2002 Eric Seigne <erics@rycks.com>
# 
#  This program is free software; you can redistribute it and/or modify
#  it under the terms of the GNU General Public License as published by
#  the Free Software Foundation; either version 2 of the License, or
#  any later version.
# 
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
# 
#  You should have received a copy of the GNU General Public License
#  along with this program; if not, write to the Free Software
#  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
# 
#**************************************************************************
#  File  : $$$
#  Author  : davidlucardi@aol.com
#  Modifier: andre.connes@toulouse.iufm.fr
#  Date    : 24/04/2002
#  Licence : GNU/GPL Version 2 ou plus
# 
#  Description:
#  ------------
# 
#  @version    
#  @author     David Lucardi
#  @modifier   Andre Connes
#  @project    Le terrier
#  @copyright  Eric Seigne 24/04/2002
# 
#  *************************************************************************

8. Internationalisation

Il est souhaitable de penser à l'internationalisation des logiciels pour l'utilisateur (peu importe le programmeur).

8.1 Pour les traducteurs :

Les fichiers de traduction se trouvent dans le dossier msgs

Ouvrez le fichier fr.msg avec un editeur de texte.

Enregistrez-le sous le nom xx.msg, où xx désigne le code de la langue (le même que celui que vous avez choisi à l'install de la distribution).

Le fichier présente une succession de lignes de même format :

::msgcat::mcset fr "Editeur"

::msgcat::mcset fr "Reglages" "R\360glages"

Si je veux traduire en Anglais , cela devient

::msgcat::mcset en "Editeur" "Editor"

::msgcat::mcset en "Reglages" "Settings"

8.2 Pour les développeurs :

Inclure le fichier msg.tcl (ex : source msg.tcl) dans l'application en développement

Mouliner toutes les chaînes de caractères selon les principes suivants :

Chaîne de caractères Codage
"Mon texte" [mc {Mon texte}]
"Gagné en $nb essais sur $total." [format [mc {Gagne en %1$s sur %2$s.}] $nb $total]

%1 et %2 permettent de "positionner" les variables, si la traduction nécessite de les inverser, par exemple.

9. Spécification concernant le déploiement :

Les applications doivent être relogeables, c'est à dire qu'elles doivent pouvoir être installées et exécutées dans n'importe quel répertoire.
Les chemins vers des fichiers et des sous dossiers devront donc être relatifs au répertoire de base de l'application (Basedir).

Soit Home le dossier personnel de l'utilisateur, Basedir le répertoire courant de l'application et Mon_appli le nom de l'application concernée.

9.1 Les fichiers de configuration :

Nommage : mon_fichier.conf

Ils devront être installés dans Home/leterrier/Mon_appli/ ou dans un sous dossier de cette branche (ex : Home/leterrier/Mon_appli/Reglages)

Si le dossier Home n'est pas défini, ils devront être installés dans Basedir/leterrier/Mon_appli/ ou dans un sous dossier de cette branche (ex : Basedir/leterrier/Mon_appli/Reglages)

9.2 Les fichiers de log :

Nommage : mon_fichier.log

9.3 Les fichiers et répertoires de l'utilisateur :

Ils devront être installés dans Home/leterrier/Mon_appli/ ou dans un sous dossier de cette branche (ex : Home/leterrier/Mon_appli/Images)

9.4 Packaging  :