SOP 001-Programmation » Historique » Révision 10
Révision 9 (Patrice Nadeau, 2015-08-26 18:03) → Révision 10/82 (Patrice Nadeau, 2015-08-27 20:36)
h1. SOP 001-Programmation
TODO : issue:#9
Mes standards autant au niveau du style que de la documentation.
La plateforme (logiciel et matériel) est documenté dans le [[SOP_002-Environnement_informatique]].
{{lastupdated_at}} {{lastupdated_by}}
---
{{toc}}
h2. Diagrammes
Les représentations des différents processus d’un programme ou d’un circuit.
Les diagrammes DOIVENT être faits avec le logiciel Dia.
Ils PEUVENT être exportés en d’autre format.
h2. Système de gestion de version
Le logiciel "Git":http://www.git-scm.com/ DOIT être utilisé.
La version DOIT être en format: _majeur.mineur.revision_.
Les nombres majeur, mineur NE DOIVENT PAS contenir de zéro non significatif et DEVRAIT se limiter à deux chiffres.
Ex.
> Version 1.2.06
Les modifications DOIVENT se faire avec _git commit_, de la manière suivante :
* nom du fichier modifié,
* 1 espace,
* nom de l’item modifié entre parenthèses,
* un deux- points (<notextile>:</notextile>) sans espace avec l’item précédent,
* 1 espace,
* le texte du changement en anglais, commençant par une majuscule, au présent,
* un point (.)
Ex. :
> Modification ajouté manuellement
<pre><code class="bash">
git commit -m "usart.c (usart_Init): Add a new variable ctr."
</code></pre>
> Modification par un éditeur texte
<pre><code class="bash">
git commit
</code></pre>
Si les commit sont fait sans l’option *-m*, chaque fichier DOIT être séparé par une ligne vide.
h2. Code source
Les différents type de langage et de script décrit dans ce SOP.
h3. Généralités
h4. Langue
La langue (macros, variables, fonctions, commentaires, etc...) DOIT être l’anglais.
h4. Commentaires
Les commentaires DOIVENT être :
* sur la ligne précédent l’item à documenter
* en minuscules et commencer par une majuscule
h4. Nombre magique
L’utilisation de "nombre magique":http://en.wikipedia.org/wiki/Magic_number_%28programming%29#Unnamed_numerical_constants ne DOIT PAS être utilisé directement dans le code.
Il DOIVENT être définis dans une macro ou une variable globale.
h2. C
Le langage C, version C99 (ISO/IEC 9899:1999) utilisé avec le compilateur GCC.
h3. Commentaires
Les commentaires ne devant pas être inclus dans une documentation, DOIVENT être de style « C » :
<pre><code class="c">
/* Une seule ligne... */
...
/*
* Sur
* plusieurs
* lignes
*/
</code></pre>
h3. Doxygen
Chaque item DOIT être documentés de manière à générer une documentation avec le logiciel "Doxygen":http://www.stack.nl/~dimitri/doxygen/index.html.
Seulement les items définis dans les fichiers d’en-tête sont documentés par défaut.
Un commentaire Doxygen commence par *<notextile> /** </notextile>* , le compilateur le comprenant comme un commentaire ordinaire.
Les règles typographiques du [[SOP_000-Documentation]] s’appliquent :
* Gras (*@b*) : Items devant être inscrit tel quel.
* Italique & emphase (*@e*) : Items à remplacer par un choix ou nécessitant une attention particulière.
> Doxygen version ≥ 1.8.8 : Le bogue "737472":https://bugzilla.gnome.org/show_bug.cgi?id=737472 oblige de forcer le langage de la fonction dans l’exemple si on ne veut pas de numéro de ligne.
Les items DOIVENT être inscrit dans cet ordre :
<pre><code class="c">
/**
* @brief Short description
* @param[in,out] var Description. @n Possible values :
* − @b value1
* − @b value2
* @return
* @retval @b value Description
* @par Example :
* Example Title
* @code{.c}
* ...
* @endcode
* @pre Requirements
* @post Changes after the call to this function
* @see See also ...
* @note
* @warning
* @bug
* @todo
*/
</code></pre>
Des *@todo*, *@warning* et *@bug* supplémentaires PEUVENT être ajoutés dans le code.
L’item *@brief* DOIT toujours exister.
h3. Code
Le code est dans le style K&R, variante 1TBS
* Le « tab » DOIT être équivalent à 4 espaces.
* Le « backslah » DOIT être utilisé pour les lignes de plus de 80 caractères.
* Une instruction par ligne.
* Un espace avant et après un opérateur sauf pour les opérateurs « "unary":http://en.wikipedia.org/wiki/Unary_operation ».
One True Brace Style
<pre><code class="c">
int fonction (void)
{
int x;
/* the comment goes here, before the loop */
if (var != 1) {
x = x + 1;
y++;
printf("This is a long\
line that should be splitted");
} else {
/** @warning this is a Doxygen warning */
x--;
}
return(0);
}
</code></pre>
h4. Fichier entête
Avertissement
>Le gabarit template.h DOIT être utilisé.
Les fichier « header » DOIVENT contenir les déclarations des fonctions, macros et la partie « mainpage » de Doxygen.
Le nom du fichier DOIT être composé de la manière suivante :
* en minuscule
* 8 caractères maximum
* l’extension DOIT être *.h*
Une définition macro DOIT être faite pour éviter de ré-inclure le fichier.
La macro DOIT être dans le format *_fichier_h*
<pre><code class="c">
#ifndef _usart_h
#define _usart_h
...
#endif /*_usart.h*/
</code></pre>
h4. Fichier source
Le nom du fichier DOIT être composé de la manière suivante :
* en minuscule
* 8 caractères maximum
* l’extension DOIT être *.c*
h4. Librairies
Fichiers comprenant plusieurs déclarations et définitions reliés entre eux.
* Le nom DOIT respecter les standards ([[SOP_001-Programmation#Fichiers-Entêtes|1]] & [[SOP_001-Programmation#Fichiers-Sources|2]]) et être significatifs.
* Un fichier d’entête DOIT toujours exister.
* Les items sont précédés du nom de la librairie (minuscule) et séparés par un « underscore » (_).
L’utilisation de macros DOIT être utilisé au lieu de constates globales.
Il NE DEVRAIT PAS exister de de variables globales.
h4. Déclarations locales
Une déclaration n’ayant qu’une visibilité locale DOIT être précédé d’un « underscore » (_) et être de classe *static*.
<pre><code class="c">
/**
* @brief Local function
**/
static void _LocalFunc(void)
{
...
return;
}
</code></pre>
h4. Items désuets
Les déclarations ne devant plus être utilisés, DOIVENT générer un message lors de la compilation (*-Wall*) si un appel est effectué.
L’attribut *<notextile> __attribute__((deprecated)) </notextile>* DOIT être ajouté à la déclaration.
La documentation DOIT indiquer les substituts à utiliser.
<pre><code class="c">
/**
* @brief OldFunction
* @detail will generate a warning if used
* @see @b NewFunction
*/
int OldFunction(void) __attribute__((deprecated));
</code></pre>
h4. Constantes
La déclaration DOIT inclure aussi la définition.
Utilisé au lieu d’une macro quand le type ou la visibilité de la variable doit être définis.
* En majuscule
* Séparé par un «underscore» (_) si contient plusieurs mots
* De classe _static_ ou _extern_ selon le besoin
<pre><code class="c">
/**
* @name List of constants
* @{
*/
/**
* @brief Local const
*/
static int _PI = 3.15;
/**
* @brief The initialization string of the project
*/
static const char INIT_STR[6] = {'P', 'O', 'W', 'E', 'R'};
/**
* @brief Global const in the random library
*/
extern int random_MAX = 25;
/**
* @}
*/
</code></pre>
h4. Typedef
Issue #18
h4. Variables
Format
* En minuscule.
* Séparé par un « underscore » (_) si contient plusieurs mots.
Définition de variables
<pre><code class="c">
/** @brief Local variable */
int _ctr;
/** @brief Global variable from the random librairy */
int random_ctr;
</code></pre>
h4. Structures
Format
* En minuscule, séparé par des «underscores» si nécessaire.
Définition de structures
<pre><code class="c">
/**
* @brief Structure for a local menu
* @see MenuSelect
*/
struct menu {
/** @brief Character used for the item */
char choice;
/** @brief Description of the item */
char *item;
};
</code></pre>
h4. Fonctions
Le nom est formé d’une lettre majuscule pour chacune des premières lettres des mots.
Le nom DOIT être dans un deux formats suivants :
* ActionItemAttribut, où _Action_ signifie :
** *Get* : Lis un registre
** *Read*, *Write* : Lis ou écris dans un fichier
** *Set* : Écris une valeur prédéfini dans un registre
** *Init* : Fonction d’initialisation
* isItemEtat
** *is* : Verifie si _Item_ est dans l’état _Etat_
Exception
> Les fonctions définies dans une librairie de bas niveau pour du matériel (« driver »). Dans ce cas, le nom définis dans le « datasheet » aura préséance. Ex. ReadRegister.
Une fonction DEVRAIT retourner une valeur.
Dans le cas d'un « oui/non », la valeur DOIT être :
* Succès : *0*
* Erreur : *1*
> L'utilisation d'un type booléen (*true* & *false*) est permise avec *<stbool.h>* (C99).
Dans le cas d'une fonction retournant un pointeur :
* Erreur : *NULL*
* autre valeur : adresse du pointeur
Définition de fonctions
<pre><code class="c">
/**
* @brief Check if a timer is set
* @param[in] nb Timer number. @n Possible values :
* − @b TIMER_1
* − @b TIMER_2
* @return
* @retval true Timer @e nb is set
* @retval false Timer @e nb is NOT set
* @par Example :
* Check if the timer is set
* @code{.c}
* ...
* result = isTimerSet();
* ...
* @endcode
* @pre TimerInit
**/
static bool isTimerSet(uint8_t nb);
/**
* @brief Set the led to green
**/
SetLedColor(GREEN);
/**
* @brief Set register of the chip XYZ
*
* The name does not follow the standards but does match the datatsheet
* This is a local function not meant to be called outside this librairy
**/
static void _WriteReg(void);
</code></pre>
h3. Macros
Les directives du préprocesseur C.
* Utilisé dans le code source et les fichiers entête.
* DOIT toujours commencer à la colonne 0.
h4. include
Pour inclure d’autres fichier comme les fichiers entête.
>N’est pas documenté dans Doxygen.
h4. ifdef / ifndef
Surtout utiliser pour des options de compilation sur différentes plateforme.
>N’est pas documenté dans Doxygen.
<pre><code class="c">
#ifndef usart_AVR
#error "usart.h is not supported on this AVR !"
#endif
</code></pre>
h4. error
Affiche une erreur et arrête la compilation
>N’est pas documenté dans Doxygen.
<pre><code class="c">
#ifndef __test__
#error "Error !"
#endif
</code></pre>
h4. #warning
Affiche une erreur mais n’arrête la compilation
>N’est pas documenté dans Doxygen.
<pre><code class="c">
#ifndef __test__
#warning "Warning !"
#endif
</code></pre>
h4. define
Définis une valeur au moment de la compilation.
* Format
** En majuscule.
** Séparé par un «underscore» si contient plusieurs mots.
* Doxygen
** @brief
** @name pour les listes de macros (regroupement dans la documentation)
Définition de macros
<pre><code class="c">
/**
* @name Mathematical macros listed together
* @{
*/
/** @brief Value for PI */
#define _PI 3.14
/** @brief Another number */
#define _MAGIC_NUMBER 42
/**
* @}
*/
/** @brief Even parity */
#define usart_PARITY_EVEN 'e'
</code></pre>
h3. Atmel AVR
Particularités pour les micro-contrôleurs AVR d’Atmel.
* Progmem : Pour mettre une fonction en Flash au lieu de SRAM.
** Le nom de la fonction est suivie de *_P*.
* main : Ne revient jamais à un niveau supérieur.
** Définir la fonction main avec l’attribut *noreturn*.
** La boucle sans fin la plus optimisé est le *for (;;)*.
* Atomic : Opérations ne devant pas être interrompus.
Particularités pour AVR
<pre><code class="c">
/**
* @brief Progmem function
* @return An unsigned 8 bits integer
*/
uint_8t PrintString_P()
/* main function */
void main(void) __atribute__((noreturn))
{
...
/* never return */
for (;;) {
}
}
/* atomic operations */
#ifndef S_SPLINT_S
ATOMIC_BLOCK(ATOMIC_RESTORESTATE) {
/*
* operations that must not be interupted
* like loading a 16 bit register with a 8 bit register
*/
}
#endif
</code></pre>
h3. Distribution
Les fichiers suivants DOIVENT être inclus dans une distribution en format *tar.gz*.
* ChangeLog
* README
* Files.lst
* Makefile
* Makefile.mk
* LICENSE.txt
* *.c
* *.h
* projet.pdf (généré par Doxygen)
Avec mon makefile :
<pre><code class="bash">
make dist
</code></pre>
h3. Modifications
Un changement à un fichier (source ou en-tête), doit se refléter dans _Git_.
Chaque changement est fait avec :
<pre><code class="bash">
git add nom_fichier
git commit
</code></pre>
La ligne DOIT
* être au temps présent
* être en anglais
* se termine par un point
* être dans le format suivant :
> La partie _section_ est facultative
<pre><code class="text">
fichier1 (fonction) <section>:
Ajoute une description au temps présent.
Décrire les bogues réglés si il y en avaient.
</code></pre>
h3. Changelog
La somme de toutes les modification doivent apparaitre dans un fichier « changelog ».
> Le standard seras celui GNU : http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs
Ce fichier doit s'appeler *ChangeLog* et DOIT être généré à partir de _Git_ (les doubles espaces ne sont pas une erreur de frappe :
<pre><code class="bash">
git log --no-merges --format="%ad %an <%aE> %n * %B" --date=short > ChangeLog
</code></pre>
h3. Validation du code
Le logiciel _splint_ est utilisé.
* Un « typecast » DOIT être utilisé lorsque détecté.
* L’utilisation du typecast *void* DOIT être utilisé lorsque qu’une fonction retourne un résultat non utilisé.
h2. Makefile
h2. Nagios
h3. Plugins
https://nagios-plugins.org/doc/guidelines.html
Un message d'une ligne (< 80 caractères) DOIT être retourné via _STDOUT_ dans le format
> *SERVICE STATUS:* texte
Les codes de retour sont les suivants:
|_. Valeur |_. Service Status |_. Description |
| 0 | OK | Le service fonctionne |
| 1 | Warning | Le service fonctionne, problème avec le seuil de la valeur _Warning_ |
| 2 | Critical | Le service ne fonctionne pas ou problème avec le seuil de la valeur _Critical_ |
| 3 | Unknow | Arguments non valides ou erreur interne (fork, tcp socket)|
Les arguments suivants DOIVENT être fournis
* *-H* (*--hostname*) :
* *-w* (*--warning*) :
* *-c* (*--critical*) :
* *-V* (*--version*) :
* *-h* (*--help*) :
L'argument _--help_ DOIT aussi appeler l'argument _--version_.
En _C_, les fonctions suivantes DOIT être utilisées :
* _print_revision_ (utils.c)
* _print_help_
* _getopt_long_ (getopt.h)
h2. Puppet
h3. Généralités
Inspiré des recommandations disponible au http://docs.puppetlabs.com/guides/style_guide.html.
* Tabulation : 2 espaces
* Largeur : 80 caractères (« backslah » (\) pour séparer une longue ligne).
* Commentaires : Style #
* Guillemets
** Simple : Pour une « string » sans variables.
** Double : Pour une « string » avec variables ayant besoin d’être extrapolé.
*** La variable doit être entourée des symboles *<notextile>{</notextile>* et *<notextile>}</notextile>*.
* Nom des ressources : DOIVENT être entouré du symbole *<notextile> ’ </notextile>*.
* Alignement de => : DOIT être aligné dans un même paragraphe.
* Ordre : Si l’attribut _ensure_ doit être inclus, il DOIT être le premier.
* Lien symbolique : DOIT être déclaré avec *ensure => link*
Ex. :
<pre><code class="ruby">
file { '/var/log/syslog':
ensure => link,
target => '/var/log/messages',
}
</code></pre>
* File mode :
** 4 chiffres
** simple guillemet
* Variables
** lettres
** chiffres
** « underscore »
h3. Documentation
http://docs.puppetlabs.com/learning/modules2.html#module-documentation
Format Rdoc (http://rdoc.rubyforge.org/RDoc/Markup.html)
* Bloc de commentaires qui commence sur la première ligne du fichier
* Titre avec le symbole *<notextile>=</notextile>*
* Séparation avec le symbole *<notextile>-</notextile>*
* Emphase (mot entouré du symbole)
** * : gras
** _ : souligné
** + : Police de caractères pour le code
* Sections
** = Class:
** == Parameters:
** == Requires:
** == Sample Usage:
* Classe
** Une classe par fichier « manifest »
h2. Script
h3. Bash
<pre><code class="bash">
#/bin/bash
function print_revision {
}
function print_help {
print_revision
}
</code></pre>
h3. Perl
<pre><code class="perl">
</code></pre>
h3. PowerShell
Version 4.0. Supporte :
* Windows 8.1 (natif)
* Windows Server 2012 R2 (natif)
* Windows 7 SP1
* Windows Server 2008 R2 SP1
* Windows Server 2012
h4. Fichier
Le fichier DOIT être composé de la manière suivante :
* L’extension est .ps1
* Une longue ligne peux être séparée avec un « back tick » (‘).
h4. Commentaires
L’aide est accéder par _Get-Help_
<pre>
#REQUIRES -Version 2.0
<#
.SYNOPSIS
A brief description of the function or script.
This keyword can be used only once in each topic.
.DESCRIPTION
A detailed description of the function or script.
This keyword can be used only once in each topic.
.NOTES
File Name
: xxxx.ps1
Author
:
Prerequisite
: PowerShell V2 over Vista and upper.
Copyright 2011 -
.LINK
Script posted over:
http://
.EXAMPLE
Example 1
.EXAMPLE
Example 2
#>
</pre>
h2. Vim
* Entête (en commentaires)
** Titre
** Last Change:
** Maintainer:
** License: This file is placed in the public domain.
* Autre mots reconnus
** BUG: (Error:)
** TODO:
** Note:
** FIXME
h2. Références
Références ayant servis à ce document.
"ChangeLog":http://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs
"GNU deprecated attribute":http://gcc.gnu.org/onlinedocs/gcc-3.2.3/gcc/Type-Attributes.html