Ce document présente les règles d'édition d'un programme Nasgaïen en ruby. ====== But de ce guide ====== 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 ( [[ http://www3.sympatico.ca/leif_thande/nasgaia/ngadoc/coding_rules.html | voir les coding rules bash ]] ). ===== Les trucs de base à savoir ===== * 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. ====== Les Fichiers ====== 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. ===== En-tête ===== L'en-tête doit contenir les informations suivantes : - Nom de l'auteur et son adresse de courriel - Licence sous laquelle est placé le code source, dans notre cas la GPL - 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? ) ===== Includes,require et load ===== * 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 ===== Variables Globales ===== à 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. ===== Les classes ===== à 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). ===== Les modules ===== à débattre 1, plusieurs classes ? forcément des classes dedans ? guiguilinxu: voir mon commentaire sur les classes ===== Les méthodes ===== Chaque fonction doit être précédée d'un commentaire incluant une explication : - Du rôle de la fonction - Du rôle et de la nature des arguments - De la valeur de retour et la façon dont elle est retournée - 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 ==== Méthodes privées ==== * 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... ==== Méthodes Publiques ==== * 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. ==== Section Main (le code) ==== Cette section contient la procédure globale de votre script. ===== Le code ===== ==== L'indentation ==== 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 ==== 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 ==== Squelette de fonctions ==== === Règles générales === * 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. === if === * 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. === unless === * 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) === each === * ensembledevaleur est ici un tableau ou un hash en general ensemblevaleurs.each do |élement(s)| code end === for === * Avec un **for classique** : for (valeurdepart; condition; incrementation) do code end * avec un **for ... in** for valeur in structure_de_valeur do code end === *.times === * Avec la méthode **times** : valeurnumerique.times do code end === case === case variable when eventailvaleurs action1 when eventailvaleurs action2 when eventailvaleurs action3 else actionpardefaut end === while === * Avec un while while condition do (code) end === until === * Avec un until until condition do (code) end

 
cr_ruby.txt · Dernière modification: 24/08/2007 06:42 par guiguilinux
 
Recent changes RSS feed Creative Commons License Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki