Thread Frage zu der Historie der Methode <<"END" [...] END (28 answers)
Opened by Wild.Card at 2017-05-06 14:21

Linuxer
 2017-05-08 01:33
#186496 #186496
User since
2006-01-27
3891 Artikel
HausmeisterIn

user image
Naja, über "Best Practice" lässt sich trefflich streiten ;-)

Ich würde POD nehmen oder die Kommentarzeilen mit #. *Keinesfalls* würde ich mit q<> oder qq<> Strings im Void-Kontext zur Dokumentation einbauen.

Zum wie muss man sich entscheiden, was man will oder welche Vorgaben man umsetzen muss.

Die einen schreiben so eine beschreibende Dokumentation gleich als POD, andere als Code-Kommentar.
Nur Code-Erklärungen landen dann als Code-Kommentar im Quellcode, nicht in der POD.

Dann kann man sowas in den Code einbetten, oder zentral am Anfang oder am Ende (z.B. hinter die "__END__" Marke setzen).

Wieder andere schreiben nur den Code in die eine Datei (mit Code-Kommentaren) und die POD landet in einer eigenen Datei .pod.

Manche schreiben den Kommentar zur Routine in die Routine, andere schreiben den über die Routine.

Da kann man schwer zu einer "Best Practice" raten, finde ich. Es hat alles seinen Vor- und Nachteil und man muss da nach Möglichkeit seinen eigenen Stil finden; bzw. bei Gemeinschaftsprojekten mit seinem Team einen Stil finden, den alle zu pflegen bereit sind.


Wenn man dann einen Stil gefunden und den richtigen Editor im Einsatz hat, kann man sich auch Shortcuts bauen, die dann beispielsweise ein Gerüst aus POD und Sub-Routinen-Code aus einem vordefinierten Template liest und einfügt. So spart man sich dann die Tipparbeit für das Gerüst.


Auf jeden Fall sei zu einem Editor geraten, der sowohl POD als auch Code zusammenklappen kann (idealerweise konfigurierbar), damit man die Teile ausblenden kann, die einen gerade nicht interessieren.



Hilfe zur POD sollte "perldoc perlpod" liefern können, oder die Seite: Perldoc:perlpod


Hier ein Beispiel mit eingebetteter POD:

doc.pl (7.5kb): more

Code (perl): (dl )
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
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

#! perl
use strict;
use warnings;
use 5.010;


=head1  doc.pl

doc.pl ist ein Beispielskript wie man POD zur Dokumentation in ein
Skript integrieren koennte. Die POD kann im Quelltext oder alternativ 
mit dem Kommando "perldoc doc.pl" gelesen werden.

=cut


# Dieser Kommentar ist nicht in der POD, sondern nur für den Programmierer

=head2 Module

doc.pl benutzt derzeit keine weiteren Module (abgesehen von 'strict' und
'warnings'. Hier koennte man die Erklaerungen auflisten, warum man diese
weiteren Module eingebunden hat oder welche Features/Funktionen man aus 
diesen Modulen verwendet.

=over 4

=item CGI

Das Modul 'CGI' wird geladen, weil wir es koennen. Benutzt wird es nicht.

=back

=cut

# Welche weiteren Module brauchen wir:
use CGI;


#####################################################################
# SUB ROUTINEN

=head3 Sub Routinen

Dieses Skript definiert folgende Subroutinen:

=cut

=head4 sub foo

foo() gibt einfach den String "foo\n" auf STDOUT aus.

=cut 

sub foo {
        # wieder ein Kommentar für den Programmierer; z.B.
        # um komplexere Interna zu erläutern oder Hinweise
        # zu geben, warum man etwas genau so macht; hier z.B.:
        # Wir koennen es eben:
        say "foo";
}

=head4 sub bar

bar(arg1, arg2, ...) gibt die uebergebenen Argumenten zeilenweise
nach STDOUT aus.

=cut

sub bar {
        say for @_;
}


#####################################################################
# HAUPTPROGRAMM

foo();
bar( qw( 1 2 3 ) );



Aufgerufen als "perldoc doc.pl" schaut es so aus:
perldoc doc.pl
Code: (dl )
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
doc.pl
    doc.pl ist ein Beispielskript wie man POD zur Dokumentation in ein
    Skript integrieren koennte. Die POD kann im Quelltext oder alternativ
    mit dem Kommando "perldoc doc.pl" gelesen werden.

  Module
    doc.pl benutzt derzeit keine weiteren Module (abgesehen von 'strict' und
    'warnings'. Hier koennte man die Erklaerungen auflisten, warum man diese
    weiteren Module eingebunden hat oder welche Features/Funktionen man aus
    diesen Modulen verwendet.

    CGI Das Modul 'CGI' wird geladen, weil wir es koennen. Benutzt wird es
        nicht.

   Sub Routinen
    Dieses Skript definiert folgende Subroutinen:

   sub foo
    foo() gibt einfach den String "foo\n" auf STDOUT aus.

   sub bar
    bar(arg1, arg2, ...) gibt die uebergebenen Argumenten zeilenweise nach
    STDOUT aus.


Im Anhang noch ein Bild, wie das im Editor aussehen kann (Vim).


Und nun mach ich Schluß hier; ist schon zu spät geworden. Evtl. Fehler könnten der fortgeschrittenen Stunde geschuldet sein.
Anhänge
image/png
993 x 810
doc_pl.png
doc_pl.png

Last edited: 2017-05-08 01:38:59 +0200 (CEST)
meine Beiträge: I.d.R. alle Angaben ohne Gewähr und auf Linux abgestimmt!
Die Sprache heisst Perl, nicht PERL. - Bitte Crossposts als solche kenntlich machen!

View full thread Frage zu der Historie der Methode <<"END" [...] END