# 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

    git commit -m "usart.c (usart_Init): Add a new variable ctr."

> Modification par un éditeur texte

    git commit

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 :

``` 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

*/

```

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

``` 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);

}

```

#### 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*

``` c

#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*.

``` c

/**

* @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

    /** 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;

#### Variables

Format :

* En minuscule.

* Séparé par un « underscore » (_) si contient plusieurs mots.

Définition de variables

    /** @brief Local variable */

    int _ctr;

    /** @brief Global variable from the random librairy */

    int random_ctr;

#### Structures

Format

* En minuscule, séparé par des «underscores» si nécessaire.

Définition de structures

    /**

    * @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;

    };

#### 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 la librairie **\<stbool.h\>** (C99).

Dans le cas d'une fonction retournant un pointeur :

* Erreur : **NULL**

* Autre valeur  : adresse du pointeur

Définition de fonctions

``` 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);

```

### 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.

``` c

#ifndef __test__

    #error "Error !"

#endif

#### #warning

Affiche une erreur mais n’arrête la compilation

>N’est pas documenté dans Doxygen.

    #ifndef __test__

    #warning "Warning !"

    #endif

#### #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

    /**

    * @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

``` bash

#/bin/bash

function print_revision {

}

function print_help {

    print_revision

}

```

### Perl

### 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 :

* 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)