Guide des bonnes pratiques de codage Matlab

Cette page est en construction et nécessite votre contribution. N'hésitez pas à proposer des règles ou des trucs, à les expliquer et à les illustrer avec des exemples. La structure de cette page se clarifiera au fur et à mesure que son contenu prendra forme. N'hésitez à vous servir des questions ci-dessous comme points de départ et à en suggérer de nouvelles.

Variables et équations

• Le nom pour les variables qui font directement référence à des équations mathématiques ou à des constantes bien établies devrait s'y apparenter le plus possible et être court (ex. g pour la gravité, u, v, w pour les courants, N pour la concentration de nitrate, etc).
• Utilisez l'écriture complète des lettres grecques (ex. lambda, phi, rho);
• Utilisez la barre de soulignement uniquement pour faire référence à une variable qui s'exprime avec un indice (ex: rho_0, sigma_t);
• Si le code est basé sur des équations tirées d'un article particulier ou d'un livre, respectez le plus possible la convention utilisée dans le document de référence;
• Exprimez les dérivées avec la lettre 'd' (ex: dt pour le pas de temps ou pour désigner un interval d'échantillonnage, dx pour un pas de grille, dTdx pour le gradient horizontal de température);
• Pour les indices d'une grille spatiale utilisez les indices i, j, et k où i et j représentent l'espace horizontale et k l'espace vertical. Si nécessaire, ajouter d'autres lettres à l'indice mais en commençant toujours par i, j, ou k (ex. iGrille1, iGrille2).
• Pour l'indice temporel, utilisez la lettre n ou, au besoin, une variable qui commence par la lettre n.
• Pour toutes les variables qui ne font par référence directement à une équation mathématique utilisez un nom de variable qui exprime le plus clairement possible sa fonction tout en restant succinct.
• Utiliser le convention du lower Camel Case, c'est-à-dire en séparant les mots qui forment une même variable avec une lettre majuscule mais en commençant par une minuscule (ex. samplingFrequency, fileName).
• Comme mentionné plus haut, réservez l'utilisation de la barre de soulignement seulement pour faire référence à un indice d'une variable mathématique. Donc, ne pas nommer une variable sampling_frequency mais plutôt respectez le standard du lower Camel Case.
• Lorsque des variables physiques et des variables biologiques se côtoieent dans une même fonction, les variables biologiques devraient être écrites avec 3 lettres minuscules afin d'éviter certaines confusions (ex. N pour nitrate ou fréquence de Brunt-Vaïsälä).

Vous trouverez ci-dessous une liste de noms de variables qui respectent les règles précédentes:

% Paramètres
g                  % accélération gravitationnelle
...

% Variables physiques
u                  % composante zonale du courant (selon x)
v                  % composante méridionale du courant(selon y)
w                  % composante verticale du courant (selon z)
T, temp            % température (in situ)
S, salt            % salinité (psu)
SA                 % salinité absolue (calculée avec TEOS-10)

% Variables biologiques
nit                % nitrate
phy                % phytoplancton
amm                % ammonium
ldn                % azote labile dissous (labile dissolved nitrogen)
det                % detritus
zoo                % zooplancton
bac                % bactéries
oxy                % oxygène dissous
pho                % phosphate
nut                % nutriment (englobe plusieurs espèces)
sil                % silice / silicate
...

Comment bien rédiger l'aide?

Utilisez le canevas suivant pour l'en-tête de vos codes. Ce canevas a été produit par Denis Gilbert (IML).

function [output1,output2] = function_name(input1,input2,input3)
%FUNCTION_NAME - One line description of what the function or script performs (H1 line)
%Optional file header info (to give more details about the function than in the H1 line)
%Optional file header info (to give more details about the function than in the H1 line)
%Optional file header info (to give more details about the function than in the H1 line)
%
% Syntax:  [output1,output2] = function_name(input1,input2,input3)
%
% Inputs:
%    input1 - Description
%    input2 - Description
%    input3 - Description
%
% Outputs:
%    output1 - Description
%    output2 - Description
%
% Example: 
%    Line 1 of example
%    Line 2 of example
%    Line 3 of example
%
% Other m-files required: none
% Subfunctions: none
% MAT-files required: none
%
% See also: OTHER_FUNCTION_NAME1,  OTHER_FUNCTION_NAME2
 
% Author: FirstName FamilyName
% Work address
% email: 
% Website: http://www.
% May 2004; Last revision: 12-May-2004

%------------- BEGIN CODE --------------

Enter your executable matlab commands here

%------------- END OF CODE --------------

Quand doit-on mettre des espaces?

On indente toujours les boucles de quelques espaces, généralement deux ou plus. Aussi on met un espace avant et après les signes d'égalité et d'inégalité ainsi que les opérations d'addition et de de soustractions. Par exemple:

for i = 1:iMax
    for j = 1:jMax
        a = a + b;
    end
end

Pour les multiplications on ne met pas nécessairement d'espace car en mathématique il suffit de coller deux variables pour signifier une multiplication. On ne met pas d'espace non plus autour des parenthèses. Par exemple:

a = (b + c*d)/4 - kappa*delta

Pour faciliter la clarté de lecture d'un bloc d'énoncés on peut mettre plus qu'un espace entre les signes d'égalité de sorte à former une sorte de tableau. Par exemple:

nit       = a*exp(b/z);
epsilon   = nu*(dudz)2;
iceStress = kappa*dCdx
dragCoef  = Cd*U^2;

Dois-je documenter en anglais ou en français?

Les codes bien faits et bien documentés se partagent parmi la communauté scientifique internationale. À cette fin, l'idéal est de produire des codes documentés en anglais et qui utilisent des noms de variables en anglais.

Documents pertinents

Le document MatlabStyle5p1 en est un duquel on pourrait s'inspirer en l'adaptant à l'océanographie.