Syntax Dokumentation
vom 15. May 2009Nach langer Abstinenz wieder mal ein kleiner Beitrag zum Thema Dokumentation. Neulich schaute ich mir die Syntax zu SQLite an und war begeistert! Eine solch hervorragende Dokumentation habe ich schon lange nicht mehr gesehen.
Normalerweise sehen Syntax-Definitionen so aus:
Seit ich programmiere, wird die Syntax so oder in abgeänderter Form dargestellt. Alles was in eckigen Klammern ist ist optional. Das Pipe-Symbol stellt ein "oder" dar. Die türkisen Hervorhebungen stellen Unterausdrücke dar, die nochmal separat beachtet werden müssen.
In der SQLite Dokumentation wurde der selbe Sachverhalt in einem "Flussdiagramm" bzw. einem Automaten dargestellt:
Welch angenehme Überraschung! Die Syntax lässt sich um einiges leichter lesen und verstehen. Wieso wird diese Darstellungsweise nicht immer verwendet? Weil es früher in ASCII unmöglich war? Oder weil es zu umständlich ist? Ne. Weil es nicht parsbar ist? Kann nicht sein, dafür gibts die BNF. Wenn mir jemand einen triftigen Grund nennen kann, bitte ich dies in den Kommentaren zu tun :)
Auch toll gemacht ist in diesem Zusammenhang ist strfriend.com. Hier werden reguläre Ausdrücke durch eine ähnliche Darstellung visualisiert. Leider unterstützt dieses Tool nur einen Bruchteil vom PCRE Quasi-Standard und man muss sich auf einfache Ausdrücke beschränken.
Und wenn wir schon beim Graphen malen sind: Wer "mal schnell" ein UML-Diagramm zeichnen möchte, aber dafür kein Zeichenwerkzeug bemühen will, kann sich mal yuml.de anschauen. Damit lassen sich über die URL Diagramme generieren!
Kommentare
Bei der verwendeten Darstellung handelt es sich um eine Form die sogar explizit als Syntaxdiagramm bekannt ist. Stammt aus der theoretischen Informatik.
Ich gebe dir vollkommen recht, dass es eine wesentlich lesbarere Form der Darstellung ist als einfach nur Text. Das ganze begegnet einem zum Beispiel auch wenn man mit ANTLRWorks Lexer/Parser für eine Sprache mit einer gegebenen (aber vllt nicht schön lesbaren) Grammatik erstellt.
Da kann man dann auch schön angezeigt bekommen, was an welcher Stelle vorkommen kann/muss/darf.
lg
Till :o)
Aber da die Syntax ist unvollständig ist, kann man sowas leider auch nur verwenden wenn es wichtige Teile wie die meistbenutzten SQL-Operatoren gibt. Ich glaube deshalb wird das nicht öfters benutzt.
Gruß Marc
hier ist Andi von IBM. Hast mich bestimmt schon erkannt :). Diese Darstellungsform wurde von Oracle übernommen. Schau dir mal die Doku von Oracle an.
http://download.oracle.com/docs/cd/B14117_01/server.101/b10759/statements_10002.htm
Oracle geht sogar noch etwas weiter und stellt die Syntax zur Verfügung.
http://download.oracle.com/docs/cd/B14117_01/server.101/b10759/img_text/subquery.htm
Finde es eine beinahe perfekte Mischung.
In diesem Sinne "leg dich wieder hin"
Beste Grüße
Andi
Unter http://www-cgi.uni-regensburg.de/~brf09510/syntax.html findest du eine Seite, mit der du aus einer Grammatik einen Syntaxbaum machen kannst!
Echt nicht uninteressant!
Gruß
Andreas
@Till: Magst mir mal deine Ausarbeitung über ANTLR aus AKSE schicken? :)
@Marc: Das stimmt. Will man die komplette Syntax in so einem Diagramm abbilden, wird es hoffnungslos unübersichtlich.
@Andi: Ja, die Mischung machts. Aber ein Bild ist trotzdem immer aussagekräftiger als ein Block Text mit tausend Klammern und Pipes. Weitermachen.
@Andreas: Danke für den Link!!
