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.

Quel nom donner à une variable?

Équations

- Le nom pour les variables qui font directement référence à des équations mathématiques ou a des constantes bien établis devrait s'y apparenter le plus possible et être courts (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 temporelle utilisez la lettre n, ou au besoin une variable qui commence par la lettre n.

Autres variables

- Pour toutes les variables qui ne font par référence directement à une équation mathématique utilisez une nom de variable qui exprime le plus clairement possible sa fonction mais en restant succinct.

- Utiliser le convention du "lower Camel Case" c'est-à-dire séparez 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;

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

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.