h1. SOP 001-Programmation

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

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

/* Une seule ligne... */

...

/*
* Sur
* plusieurs
* lignes
*/

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

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

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

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

#ifndef _usart_h
#define _usart_h
...
#endif /*_usart.h*/

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

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.

/**
* @brief Local function
**/
static void _LocalFunc(void)
{
...
return;
}

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

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

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

/**
 * @}
 */

h4. Typedef

Issue #18

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

h4. 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;
};

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

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

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.

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

h4. error

Affiche une erreur et arrête la compilation

N’est pas documenté dans Doxygen.

#ifndef __test__
#error "Error !"
#endif

h4. #warning

Affiche une erreur mais n’arrête la compilation

N’est pas documenté dans Doxygen.

#ifndef __test__
#warning "Warning !"
#endif

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

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

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

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

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 :

make dist

h3. 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)  : 
Ajoute une description au temps présent.
Décrire les bogues réglés si il y en avaient.
 

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 :

git log --no-merges --format="%ad  %an  <%aE> %n * %B" --date=short > ChangeLog

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 { et }.
• Nom des ressources : DOIVENT être entouré du symbole ’ .
• 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 »

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 =
• Séparation avec le symbole -
• 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

#/bin/bash

function print_revision {
}

function print_help {
    print_revision
}

h3. Perl

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

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

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