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

Documents pertinents

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