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

---

• Contenu
• SOP 001-Programmation
  • Diagrammes
    • LibreOffice Draw
  • Système de gestion de version
  • Code source
    • Généralités
      • Langue
      • Commentaires
      • Nombre magique
  • C
    • Commentaires
    • Doxygen
    • Code
      • Fichier entête
      • Fichier source
      • Librairies
      • Déclarations locales
      • Items désuets
      • Constantes
      • Typedef
      • Variables
      • Structures
      • Fonctions
    • Macros
      • #include
      • #error
    • Perl
    • PowerShell
      • Fichier
      • Commentaires
  • Vim
  • Références

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 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 (:) 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 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.

Seulement les items définis dans les fichiers d’en-tête sont documentés par défaut.
Un commentaire Doxygen commence par /* * , 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.

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 (1 & 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

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

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

#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
GNU deprecated attribute