SOP 001-Programmation » Historique » Révision 30
Révision 29 (Patrice Nadeau, 2018-03-24 17:09) → Révision 30/82 (Patrice Nadeau, 2018-03-24 17:12)
# SOP 001-Programmation
Mes standards autant au niveau du style que de la documentation.
La plate-forme (logiciel et matériel) est documenté dans le [[SOP_002-Environnement_informatique]].
{{lastupdated_at}} {{lastupdated_by}}
---
{{toc}}
## 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.
### LibreOffice Draw
Icônes :
* Cisco : http://www.cisco.com/web/about/ac50/ac47/3015_jpeg.zip
* http://www.vrt.com.au/downloads/vrt-network-equipment ou http://extensions.libreoffice.org/extension-center/vrt-network-equipment/
## 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.
## Code source
Les différents type de langage et de script décrit dans ce SOP.
### Généralités
#### Langue
La langue (macros, variables, fonctions, commentaires, etc...) DOIT être l’anglais.
#### Commentaires
Les commentaires DOIVENT être :
* sur la ligne précédent l’item à documenter
* en minuscules et commencer par une majuscule
#### 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.
## C
Le langage C, version C99 (ISO/IEC 9899:1999) utilisé avec le compilateur GCC.
### Commentaires
Les commentaires ne devant pas être inclus dans une documentation, DOIVENT être de style « C » :
/* Une seule ligne... */
...
/*
* Sur
* plusieurs
* lignes
*/
### 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 :
/**
* @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
*/
Des *@todo*, *@warning* et *@bug* supplémentaires PEUVENT être ajoutés dans le code.
L’item *@brief* DOIT toujours exister.
### 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
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);
}
#### Fichier entête
Avertissement
>Le gabarit template.h DOIT être utilisé.
Les fichiers « 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*
#ifndef _usart_h
#define _usart_h
...
#endif /*_usart.h*/
#### 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*
#### 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.
#### 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*.
/**
* @brief Local function
**/
static void _LocalFunc(void)
{
...
return;
}
#### 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 ** __attribute__((deprecated)) ** DOIT être ajouté à la déclaration.
La documentation DOIT indiquer les substituts à utiliser.
/**
* @brief OldFunction
* @detail will generate a warning if used
* @see @b NewFunction
*/
int OldFunction(void) __attribute__((deprecated));
#### 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
Ex. :
/**
* @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;
/**
* @}
*/
#### Typedef
Format :
* En minuscule, suivie de *_t*
Définition de typedef
<pre><code class="c">
/** Unsigned integer 8 bits */
typedef unsigned int new_t
/** Type of structure in the ds1305 library */
typedef struct {
/** @brief last two digits : ≥ 00, ≤ 99 */
uint8_t year;
/** @brief 01 - 12 */
uint8_t month;
/** @brief 01 - 31 */
uint8_t date;
/** @brief 1 - 7 */
uint8_t day;
/** @brief 00 - 23 */
uint8_t hours;
/** @brief 00 - 59 */
uint8_t minutes;
/** @brief 00 - 59 */
uint8_t seconds;
} ds1305_time_t;
</code></pre>
#### 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>
#### 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>
#### 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>
### Macros
Les directives du préprocesseur C.
* Utilisé dans le code source et les fichiers entête.
* DOIT toujours commencer à la colonne 0.
#### include
Pour inclure d’autres fichier comme les fichiers entête.
>N’est pas documenté dans Doxygen.
#### ifdef / ifndef
Surtout utiliser pour des options de compilation sur différentes plateforme.
>N’est pas documenté dans Doxygen.
#ifndef usart_AVR
#error "usart.h is not supported on this AVR !"
#endif
#### error
Affiche une erreur et arrête la compilation
>N’est pas documenté dans Doxygen.
#ifndef __test__
#error "Error !"
#endif
</code></pre>
#### #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>
#### 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'
### 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
/**
* @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
### 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 :
make dist
### Modifications
Un changement à un fichier (source ou en-tête), doit se refléter dans _Git_.
Chaque changement est fait avec :
git add nom_fichier
git commit
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
fichier1 (fonction) <section>:
Ajoute une description au temps présent.
Décrire les bogues réglés si il y en avaient.
### 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 :
git log --no-merges --format="%ad %an <%aE> %n * %B" --date=short > ChangeLog
### 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é.
## Makefile
## Nagios
### 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)
## Puppet
### 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. :
file { '/var/log/syslog':
ensure => link,
target => '/var/log/messages',
}
* File mode :
* 4 chiffres
* simple guillemet
* Variables
* lettres
* chiffres
* « underscore »
### 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 »
## Script
### Bash
#/bin/bash
function print_revision {
}
function print_help {
print_revision
}
</code></pre>
### Perl
<pre><code class="perl">
</code></pre>
### 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
#### Fichier
Le fichier DOIT être composé de la manière suivante :<F8>
* L’extension est .ps1
* Une longue ligne peux être séparée avec un « back tick » (‘).
#### Commentaires
L’aide est accéder par _Get-Help_
#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
#>
## 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
## 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)