Cet article traite du bon usage des commentaires dans Matlab. Comme pour tout langage de programmation, il est très important de commenter son code au fur et à mesure de sa rédaction — jamais après, car après signifie généralement jamais. De plus, dans Matlab, les commentaires placés en début de code vont servir d’aide pour la fonction, comme nous le verrons un peu plus loin.
Ajout de commentaires
Les commentaires sont introduits par le caractère « % ». L’interpréteur Matlab ignore tous les caractères entre le « % » et la fin de la ligne, exactement comme le « // » du C++. Il n’existe malheureusement pas de commande pour commenter tout un bloc de code comme en C. Cependant, la plupart des éditeurs de texte ainsi que l’éditeur intégré de Matlab permettent de le faire, en ajoutant un « % » au début de chaque ligne du code sélectionné. Il existe enfin une alternative, quelque peu « sauvage », mais qui marche très bien, qui consiste tout simplement à inclure le bloc à commenter dans une structure « if » toujours fausse :
if 0
(votre code)
end
Aide de la fonction
Chaque fois que vous écrivez une fonction, commencez par l’aide de la fonction, même sommairement, quitte à la compléter plus tard. Le mieux est de la mettre à jour à mesure, quand vous ajoutez une nouvelle option, de nouveaux arguments, etc. Le bloc de commentaires servant d’aide doit être placé immédiatement avant ou après la déclaration de la fonction :
Première solution :
%Commentaire de l'aide
function [output1, output2] = MaFonction(input1, input2)
(votre code)
Seconde solution :
function [output1, output2] = MaFonction(input1, input2)
%Commentaire de l'aide
(votre code)
Il est à noter que vous pouvez sauter autant de lignes que vous le souhaitez entre ce commentaire et la déclaration de la fonction ou le code. Pour ma part je préfère la première solution, que je trouve plus claire à la lecture du code, mais les fonctions écrites par The Mathworks privilégient la seconde. Une fois l’aide écrite, il suffira de lancer la commande :
>> help MaFonction
pour voir s’afficher :
Commentaire de l’aide
À présent, penchons-nous sur le contenu de cette aide. Vous pouvez y mettre ce que vous désirez, néanmoins une bonne pratique consiste à :
- mettre sur la première ligne le nom de la fonction, suivi d’une brève description de son rôle ;
- détailler le comportement de la fonction suivant les arguments d’entrée et de sortie ;
- renvoyer à d’autres fonctions similaires, ou bien, dans le cadre d’un projet, aux fonctions que vous avez écrites appelées par cette fonction, ou encore la ou les fonctions qui appellent votre fonction ;
- éventuellement, signer et mettre une mention de copyright ou de licence (mais vous pouvez le faire dans un autre bloc de commentaire juste en-dessous, qui ne sera pas affiché mais qui sera lisible par ceux qui regarderont votre code) ;
- préciser, si vous ne travaillez pas avec un système de management de version (CVS, etc.), la date de début de développement de la fonction, ainsi que les dates de toutes les modifications avec une description des changements apportés ;
- tout écrire en anglais, si vous le pouvez, surtout si d’autres personnes sont amenées à reprendre votre code.
Pour ma part, j’ai adopté les conventions des fonctions Matlab de base, ce qui donne :
%MAFONCTION Brève description de ma fonction
% MAFONCTION(IN1) fait ceci.
%
% MAFONCTION(IN1,IN2) fait en outre cela.
%
% OUT = MAFONCTION(...) renvoie le résultat dans OUT.
%
% See also AUTREFONCTION1, AUTREFONCTION2.
Lors de l’appel de la fonction help, Matlab affiche le bloc en retirant les caractères « % » de début de ligne. Notons que j’ai utilisé ici des lettres capitales pour le nom des fonctions et pour les arguments d’entrée et de sortie afin d’améliorer la lisibilité de l’aide, alors que les véritables noms sont écrits en bas de casse. N’utilisez pas cette convention si vos noms de fonctions ou de variables comportent des capitales.
Nous verrons dans un prochain article comment écrire une fonction permettant d’afficher de différentes manières l’aide de toutes les fonctions d’un projet.
Indication de fin de fonction
Pour terminer, il est conseillé de bien délimiter la fin de vos fonctions, même si — ce qui est souhaitable — vous ne mettez qu’une seule fonction par M-file. La commande « end function » posant parfois problème, un commentaire fait tout aussi bien l’affaire !
