Ce guide décrit un ensemble de règles à respecter au niveau de la présentation de l’ensemble des codes sources de la distribution. Le respect de ces règles permet d’obtenir un certain niveau d’uniformité dans le code et par conséquent, permet aux développeurs et aux utilisateurs de Nasgaïa de s’y retrouver plus facilement.

L’ensemble de ces règles s’appliquent au langage de Programmation Ruby (version 1.8.2 et supérieur) utilisé par l’équipe de Nasgaïa pour la création d’une partie ses outils. Pour ce qui est des autres langages de programmation, il est recommandé d’imiter la mise en forme proposée dans ce document dans les limites permises par le langage ( voir les coding rules bash ).

• Les outils de Nasgaïa sont écrits en Bash ou en Ruby.
• Tous les codes sources sont écrits (et surtout commentés) en anglais.
• La traduction des messages se fait avec gettext.
• Éviter les caractères accentués, surtout dans les noms de variables et de fonctions.

En programmation, un code source est composé de plusieurs éléments, soit des variables, des fonctions, des procédures etc. Afin de mieux s’y retrouver, on regroupent les éléments semblables dans des sections. On ajoute aussi un commentaire de section entre chacune d’elles afin de bien délimiter les différentes sections.

Toutes les sections à l’exception de l’en-tête sont optionnelles. L’ordre proposé ne doit pas être obligatoirement suivi. Si ce modèle cause des problèmes d’ordre technique, les sections peuvent être inversées.

L’en-tête doit contenir les informations suivantes :

1. Nom de l’auteur et son adresse de courriel
2. Licence sous laquelle est placé le code source, dans notre cas la GPL
3. Un court résumé du contenu du fichier (rôle du code)

Omettre d’inclure la licence et le nom de l’auteur entraîne des risques au niveau légal. (Cet note est à mettre en valeur, hum quel norme pour ça sur le wiki? )

* require ne charge le fichier que si celui-ci n’a pas encore étét inclus : si celui-ci contient du code “actif” (c’est à dire en dehors d’une classe ou d’une fonction), faire plusieurs “require” d’affilé ne l’executera qu’une seule fois.

* load inclut systèmatiquement le fichier, autant de fois qu’elle est appelée

à débattre

• Le nom des constantes s’écrit en majuscules, et sont publiques.
• Les variables globales commencent par $
• Les variables et constantes composées de plusieurs mots utilisent le caractère underscore “_” pour séparer les mots.

• Utiliser les tables de hachage, tableaux et structures à bon escient en fonction du type et la complexité des données

• Utiliser des symboles à la place des chaine de caractère si elle ne sont pas là pour être affiché ou écrite dans un fichier, un symbole prend moins de place en mémoire.

à débattre guiguilinux: pour moi, c’est en dehors du cadre de ces coding rules : là, c’est au dev de décider comment il découpe son programme, en fonction de ses objectifs et de ses choix d’implémentation (on peut pas le faire pour lui).

à débattre 1, plusieurs classes ? forcément des classes dedans ? guiguilinxu: voir mon commentaire sur les classes

Chaque fonction doit être précédée d’un commentaire incluant une explication :

1. Du rôle de la fonction
2. Du rôle et de la nature des arguments
3. De la valeur de retour et la façon dont elle est retournée
4. Des différents codes d’erreur et de leurs significations

guiguilinux : on a une gestion des exceptions en ruby : il n’y a donc pas à gérer des codes de retour ! Le seul cas ou les codes de retour doivent être utilisés sont dans le cas de l’exit sauvage. Autre précision : lors d’un test sur un valeur, nil et false retournent faux, et totue autre valeur est considerée comem vraie : c’est une astuce tres utile a exploiter

L’utilisation d’un chiffre pour débuter un de fonction est à proscrire.

Une méthode de type “prédicat” (retournant vrai ou faux) doit par convention se finir par un ? exemple : ‘abc’.include?(’b’) –> true

Quand il existe une variante “dangereuse” d’une méthode courante, modifiant l’objet ou les arguments qui lui sont passés par exemple, on la distingue par convention par l’ajout d’un point d’exclamation pour avertir le développeur.

exemple : options.parse!

à débattre

• Le nom des fonctions privées commence par le caractère “_” (hum possible en ruby ça ?? )

guiguilinux : Possible, mais sans moi... Nous ne sommes pas en Python, et le modifieur “private” existe...

• Le nom des fonctions publiques débutent par une lettre

guiguilinux : Elle ne peuvent de toute façon pas commencer par un nombre, comme tous les autres identifieurs en Ruby.

Cette section contient la procédure globale de votre script.

L’indentation ne se fait qu’avec des caractères d’espacement.

On remplace les caractères “tabulation” par des caractères “espace”.

• 1 tabulation = 4 espaces

guiguilinux : Le “standard” Ruby est de 2 espaces, mais le 4 espaces est souvent utilisé.

Certains éditeurs de texte (exemple : Kate ) vous permette de remplacer les tabulations par des espaces. Cela devrait vous permettre de sauver bien du temps. Pour gvim dans le .vimrc rajoutez :

set expandtab " change la tabulation en espaces
set shiftwidth=4
set softtabstop=4
set tabstop=4

Les commentaires de sections doivent ressembler à ceci :

#==============================================
#       ICI LE NOM DE LA SECTION
#==============================================
  

Les autres commentaires utilisent tous simplement le caractère # :

#
# Ceci est un commentaire
#
  

ou pour un très long commentaire, on l’entour d’un =begin, =end :

=begin
   Voyons quoi écrire qui pourrait être très long.
   Hum dur à trouver.
   Je manque d'inspiration là.
   Ah je vais vous narrez une histoire drôle alors.
   Non vous ne voulez pas, tant pis.
=end

• Afin d’améliorer la visibilité du code, il est recommandé d’indenter votre code. Lorsque vous entrez dans une boucle, indentez votre code d’une tabulation. Faire de même pour chaque boucle subséquente.

• Les éléments if, elsif, else et end sont placés sur la même colonne.
• Les éléments then sont placés à la fin de la ligne et non sur une ligne séparée.

guiguilinux : Le mot clé then est complètement optionnel en Ruby, et je ne l’ai pour ainsi dire jamais utilisé ou vu utilisé, donc cette dernière remarque dépend surtout de la présence ou non du mot clé.

if (condition)
    (code si condition vraie)
elsif (condition)
    (code si condition vraie)
else
    (code)
end      

• pour un test sur une ligne écrivez

code if (condition)

guiguilinux : A éviter dès que l’instruction devient complexe, rapidement illisible.

• Les éléments unless et end sont placés sur la même colonne.

  unless (condition)
      (code)
  done

• pour un code sur une liste, écrivez

  code unless (condition)

• ensembledevaleur est ici un tableau ou un hash en general

 ensemblevaleurs.each do |élement(s)|
     code
 end

• Avec un for classique :

  for (valeurdepart; condition; incrementation) do 
      code
  end

• avec un for ... in

  for valeur in structure_de_valeur do
      code
  end

• Avec la méthode times :

  valeurnumerique.times do
      code
  end

  case variable
      when eventailvaleurs
          action1
      when eventailvaleurs
          action2
      when eventailvaleurs
          action3
      else
          actionpardefaut
  end

• Avec un while

  while condition do 
      (code)
  end

• Avec un until

  until condition do
      (code)
  end