Syntax Dokumentation

Nach 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!