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

<pre><code class="c">

	/* Une seule ligne... */

	...

	/*

	* Sur

	* plusieurs

	* lignes

	*/

</code></pre>

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

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

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

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

<pre><code class="c">

/**

* @brief Local function

**/

static void _LocalFunc(void)

{

...

return;

}

</code></pre>

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

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

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

<pre><code class="c">

#ifndef usart_AVR

#error "usart.h is not supported on this AVR !"

#endif

</code></pre>

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

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

</code></pre>

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

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

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

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

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

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

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

<pre><code class="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_

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

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