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.

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

* ...

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

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

<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