Discussion :

[Philou67430]

Bonjour,

Suite à une relecture de la FAQ perl, concernant cette question des commentaires multi-ligne, je souhaite avoir votre avis sur cette alternative que je propose, et dans quelle mesure l'une ou l'autre des solutions serait la plus indiquée.

Dans la FAQ, le commentaire multi-ligne est proposé à l'aide des commentaires Pod. Je trouve à cette solution, un certain nombre d'inconvénients :
- si le fichier en question dispose d'une documentation Pod, le fait d'ajouter les balises pod (de manière légale, c'est à dire avec des lignes vides avant et après chaque balise) autour du commentaire va en faire un morceau de documentation, ce que l'on ne souhaite pas forcément pour un commentaire
- de même, si on l'ajoute de manière illégale (c'est à dire sans les lignes vides, comme indiqué dans la FAQ), la génération de la documentation provoque une erreur POD.

POD ERRORS
Hey! The above document had some coding errors, which are explained
below:

Around line 2:
=pod directives shouldn't be over one line long! Ignoring all 2
lines of content

Cette solution a cependant l'avantage de ne pas charger en mémoire le contenu du commentaire.

Personnellement, je n'utilise pas les commentaires POD. La plupart du temps, j'utilise # sur plusieurs lignes, mais lorsqu'il m'arrive de commenter un grand nombre de ligne (par exemple, pour "masquer" temporairement un bout de code), j'utilise l'opérateur here-document.

Par exemple

Code perl :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
traitement1();
<<'OLD_CODE';
traitement2();
...
OLD_CODE
traitement10();

Cette technique est parfaitement légale, qu'il y ait ou non de la documentation POD, et sans impact sur cette dernière. Apriori, j'aurais tendance à dire qu'elle n'a pas d'impact sur la mémoire des données, puisque le contenu du here-document n'est plus référencé à la fin de l'instruction (le compilateur ne génère peut-être même pas d'instruction).
En revanche, j'ai pu constaté que le here-document est chargé en mémoire avec le programme (mais pas plus que lorsque le code était actif (même beaucoup moins)).

Que pensez-vous de cette technique alternative ?
Estimez-vous qu'elle soit plus générique que l'usage de la technique POD ?

Je n'ai pas le PBP sous la main, mais si quelqu'un en dispose, il serait peut-être intéressant d'avoir une vision des commentaires multi-lignes conseillés.

A vos avis.
Cordialement.

Philippe/

[djibril]

Moi j'ai pour habitude d'utiliser =header et =cut pour faire des commentaires multilignes.

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
=header
commentaires sur 
plusieurs lignes
=cut

Mais il est vrai que si dans le code, j'ai une documentation pod, ça pose souci et j'ai des codes d'erreur.

[Philou67430]

Mais ce n'est pas la même erreur que celle que j'ai cité, puisque la balise =header n'existe pas dans le langage POD

[djibril]

En fait en utilisant ce type de commentaires

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
=for commentaires
commentaires sur 
plusieurs lignes
=cut

sans ligne vide avant et après, donc de façon illégal, on a pas forcément de messages d'erreur pod.

Par exemple, le code suivant ne provoque pas d'erreur :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
#!/usr/bin/perl
use warnings;
use strict;
use Carp;
 
my $code = 1;
 
=for code
  mon commentaire
  multiligne
=cut
 
for (1..10) {
  print $_,"\n";
}
 
sub bonjour {
  print "bonjour\n";
}
__END__
 
=head1 code
 
ma documentation POD
 
=cut

perldoc pod.pl
code
ma documentation POD

Si je mets par contre des espaces avant et après =for =cut

mon commentaire
multiligne

code
ma documentation POD

Philou67430, quant tu dis que tu as des messages d'erreur POD, à quoi ressemble ta documentation POD ?

[Philou67430]

Si les balises sont valides, tout les commentaires apparaissent dans la doc, s'ils ne sont pas valides, les balises valides apparaissent suivi de l'erreur.
Je n'ai pas vérifié si une erreur court-circuitait la fin de perldoc, si c'est ta question.

[djibril]

Bon,

Je vais vous copier une recommandation du Best practice de Damian conway. Documentation aussi disponible dans perl perlpod.

Les directives POD =for et begin/=end permettent de créer facilement de larges blocs de texte qui seront ignorés par le compilateur et qui ne produiront pas non plus d'effet visible lorsque le fichier sera traité par un formatteur POD. Ces instructions constituent donc un moyen très pratiques d'insérer des portions de de documentation interne dans vos sources.

Le directive =for est identique à une paire begin/=end, la seule différence étant que la documentation ne concerne qu'un paragraphe, dont la fin est matérialisée par une ligne vide. Il est obligatoire d'ajouter la directive =cut pour indiquer au compilateur que la documentation est terminée et qu'il doit reprendre l'analyse du source Perl.

...
Évitez la forme =begin/=end, sauf dans le cas où les explications sont abondantes et sur plusieurs paragraphes ou bien lorsque du code est inséré dans ces explications

Exemple propre :

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
=for mon commentaire:
blablabla
blablabla
blablabla
 
=cut
# mon code
# ...
 
=for autre commentaire:
blablabla
blablabla
blablabla
 
=cut
 
=begin test:
blablabla
blablabla
 
blablabla
blablabla
 
for (1..12) {
  say $_; # plus adéquat
}
 
=end test
 
=cut

voilà, je pense que c'est la façon la plus propre pour faire du commentaire multiligne. Faudrait peut être être plus clair dans la FAQ. Mais bon j'aimerais en savoir plus sur la notation << .

[Philou67430]

L'opérateur "here-document" est celui qui permet de mettre des copier des chaines "en ligne" (inline) depuis le source.

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
 
# ici commence un "here-document"
my $texte = <<"MON TEXTE";
Ceci est le texte de $user
MON TEXTE
 
# ici reprends le cours des instructions perl

Tu voulais savoir autre chose ?

[djibril]

non, je connaissais car je l'utilise régulièrement, mais pas pour les commentaires

[Philou67430]

En général, je ne l'utilises pas pour des commentaires, mais pour commenter du code (le rendre inactif). Je vois qu'avec =for =cut, j'obtiendrai le même résultat, sans impact sur la doc POD.
Je vais sans doute revoir ma pratique

[djibril]

Pour la question de la FAQ, je vais donc faire une mise à jour sur les commentaires multiligne histoire d'être plus précis, ok ?

[Philou67430]

Oui, bonne idée.
Pour moi, le sujet est clos, merci.