Beau boulot ! :-)
Voici mes remarques et propositions :
- Vu que Nasgaia se veut être une distribution francophone :-), et tenant
compte de la remarque de Chicha, je remplacerais « Coding Rules » par «
Règles de codage Bash »
- Les Fichiers : Je trouve que l'introduction de cette section n'est pas
claire :-) En fait, quand on est au courant des discussions qui ont eu lieu
sur la ML à ce sujet, on s'y retrouve, mais pour celui qui n'est pas au
courant, je trouve ça obscur. Il faudrait compléter en disant qu'un fichier
est composé de plusieurs sections. Que chaque section commence par un
commentaire indiquant de quelle section il s'agit (avec un lien vers la
partie « Commentaires > du document). Que ces sections sont présentées
ci-dessous ...
- Les Fichiers : « L'ordre proposé ne doit pas être obligatoirement suivit »
=> suivi
- Je mettrais la note « Omettre d'inclure la licence et le nom de l'auteur
entraîne des risques au niveau légal. » dans la sous-section « En-tête »
- En-tête :
« L'en-tête doit contenir les éléments suivants » => informations suivantes ?
« Licence du logiciel » => Licence sous laquelle est placée le code source
contenu dans le fichier.
Nom de l'auteur + son email si possible
- Variables globales : Les règles ne sont pas tout à fait bonnes. Le nom des
constantes est en majuscules, les variables globales de la forme
g_sGlobalVar, les locales de la forme l_sLocalVar (voir mon post sur cette ML
à ce sujet)
- Fonctions : « L'utilisation d'un chiffre pour débuter un de fonction est à
proscrire. » Il manque "nom" :-)
Pour les noms de fonctions, j'avais proposé la forme _xFunctionName pour les
fonctions dites privées et xFunctionName pour les fonctions dites publiques ;
avec "x" indiquant la nature de la valeur retournée ou affichée : "s" string,
"i" integer, "m" mixed (c-a-d que ça peut être un string ou un nombre), "as"
array of strings, "ai" array of integers, "am" array of mixed.
- Section Main : je dirais « code principal » au lieu de procédure globale.
- Indentation : « L'indentation ne se fait qu'avec des caractères
d'espacement. » => caractères « espace ». C'est plus précis car une
tabulation est considérée comme un caractère d'espacement (même si tu le
précises après :-) ) « Chaque niveau d'indentation est constitué de 4
caractères "espace". »
De manière générale, utiliser le mot « indentation » au lieu de
« tabulation ».
« Certains éditeurs de texte (exemple : Kate ) vous permette de remplacer les
tabulations par des espaces »: permette => permettent; par des espaces => par
un nombre de caractères "espace" défini/donné
« Cela devrait vous permettre de sauver bien du temps » => de gagner du
temps ?
- Commentaires :
« Les commentaires de sections doivent ressembler à ceci » => Les en-têtes de
sections doivent ... ? (Perso, mes lignes "#========..." font 79
caractères.)
- Squelette de fonctions : « Afin d'améliorer la visibilité du code, il est
recommandé d'indenter votre code » => il est recommandé de l'indenter.
« Lorsque vous entrez dans une boucle, ... boucle subséquente. » => à déplacer
dans la partie FOR.
- IF : « Les éléments thensont » => then sont
Ce serait mieux d'utiliser <condition> au lieu de (condition) (mais il me
semble que NgaDoc provoque une erreur quand on utilise les caractères <> ou
les entities < >, faut que je regarde ça :-) ). Au pire, juste
condition sans rien autour.
- CASE :
« les commandessont alignés » => commandes sont
« Espacement » => Espacements
« Tout le reste est séparé par 4 espaces ( 1 tabulation ) » => enlever "( 1
tabulation )"
Pour l'exemple du case, j'utiliserais des noms de variables/functions plus
généraux au lieu d'un exemple réel, comme les autres exemples où on a
"condition", "code" ...
- Pour tous les mot-clés du langage bash dans le texte en général et dans les
exemples en particulier, utilise la balise <code> de NgaDoc pour les
distinguer. Pour les variables "${...}", utilise la balise <var>. Il faudra
surement revoir les styles CSS associés à ces éléments :-)
- A la place de la balise NgaDoc <example>, tu peux utiliser <file
part="chunk"> car il s'agit aussi du contenu d'un fichier :-)
- Ce serait bien qu'il y ait un exemple de code complet à la fin du document
pour résumer tout ce qui vient d'être expliqué.
++
Gontran
