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


Hier ein Beispiel mit eingebetteter POD:

doc.pl (7.5kb)

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

Last edited: 2017-05-08 01:38:59 +0200 (CEST)

Punktesysteme sind unsinnig. Programmieren ist und bleibt ein Handwerk, das muss jeder selber lernen. Das betrifft auch den Style.

In meiner beruflichen Praxis der letzten Jahre habe ich hauptsächlich gelernt, wie man es nicht machen sollte. Daher:

Notiere Kommentare so, dass man auch sieht, dass es Kommentare sind. D.h., dass POD-Tokens genausowenig einen Kommentar auszeichnen wie der q-Operator.

POD ist POD und Comment ist Comment. Semantics in mind.

MfG

Was ist an den "#" unhandlich?
Ein vernünftiger Editor kann sowas im Block setzen und löschen.

Zudem haben die weitere Vorteile wie z.B.:
* Syntax highlighting funktioniert (im Gegensatz zu q())
* Code folding funktioniert (im Gegensatz zu q())
* Suchen im Source funktioniert einfacher (im Gegensatz zu q() und teilweise pod)

Also zusammengefasst: Keinesfalls die q()-Lösung benutzen, die macht jegliche Semantik kaputt.

Zudem hätten wir die Konvention, dass es bei warnings abschalten einen Kommentar braucht. Also bräuchtest du einen Kommentar um deinen Pseudo-Kommentar zu erklären ;)

Das ist ungefähr so, wie wenn du im HTML statt <h1> ein <a href class="h1"> benutzt. Das kannst du auch irgendwie hintricksen, aber die Bedeutung eines h1 ist halt kaputt.
Last edited: 2017-05-08 09:27:44 +0200 (CEST)