ABAP DOC - mit wenig Aufwand Klassen und Methoden dokumentieren
Die Einschätzung, wie die Dokumentation eines Programms aussehen sollte, unterlag im Laufe der Zeit immer wieder Schwankungen. Früher galt eine detaillierte (und dadurch auch oft erschlagende) Dokumentation als das Maß der Dinge. Mit "Clean Code" hat sich die Ansicht darüber geändert - anstatt Aufwand in die Dokumentation zu stecken, sollte der Aufwand lieber in den Code gesteckt werden, so dass er leicht verständlich und selbsterklärend ist und dadurch keine ausführliche Dokumentation benötigt - was allerdings nicht heißen soll, dass gar keine Dokumentation mehr erstellt werden sollte.
Ein gewisses Maß an Programmdokumentation ist natürlich nach wie vor sinnvoll - wer mag schon vor einer neuen Bibliothek mit Klassen und deren Methoden stehen, ohne auch nur ein bisschen greifbare Dokumentation zu haben?
Mit ABAP DOC ist eine einfache Dokumentation innerhalb des Sourcecodes möglich, die in Eclipse / ADT hübsch aufbereitet dargestellt wird und - wenn man will - ständig präsent ist.
Hier ein einfaches Beispiel: mit recht geringem Aufwand ist hier die Klasse im Wesentlichen dokumentiert, inkl. Verweisen auf weitere Informationen, darunter die Parameter des Konstruktors sowie eine Kurzbeschreibung der EXPORT-Methode und deren Parameter:
Hat man in Eclipse die View "ABAP Element Info" aktiviert,
bekommt man - wenn der Klassenname oder der Methodenname selektiert ist - eine aufbereitete und leicht lesbare Dokumentation im entsprechenden Fenster.
Hier die Dokumentation, wenn man den Klassennamen im Editor selektiert hat:
Und genauso schön auch bei Methoden:
ABAP Doc-Kommentare werden grundsätzlich durch
"!
eingeleitet, danach folgt der Text.
Hier noch eine Auswahl weiterer Zeichenfolgen:
- Parameter:
@parameter name|documentation - Klassenbasierte Exception:
@raising name|documentation - Nicht klassenbasierte Exception:
@exception name|documentation - Zeilenumbruch:
<br/> - Absatz:<p>…</p>
- Unsortierte Liste: <ul><li>…</li></ul>
Hier noch ein paar Links zu dem Thema:
- Blog "ABAP Doc" von Michael Schneider: https://blogs.sap.com/2013/04/29/abap-doc/
- Blog "New ABAP Doc Features with NetWeaver 7.5" von Michael Schneider: https://blogs.sap.com/2015/10/21/new-abap-doc-features-with-netweaver-75/
- ABAP Doc in der SAP-Dokumentation: https://help.sap.com/doc/abapdocu_754_index_htm/7.54/de-DE/abendoccomment.htm
Es gibt noch keine Rezension.