Dateiformate sinnvoll dokumentieren
-
Hallo zusammen
Ich habe gerade im Zusammenhang mit meinem Studium eine Software geschrieben und bin nun damit beschäftigt, die Dokumentation zu verfassen. Hierbei habe ich erhebliche Mühe, das verwendete Dateiformat irgendwie sinnvoll in dieser Dokumentation zu verfassen! Gibt es hierfür bestimmte Notationen oder ähnliches?Ich meine, ich kann ja nicht irgendsowas schreiben:
In den ersten 2 Bytes sind die Anzahl der Levels gespeichert, danach folgt eine Liste von Indexen mit je 4 Bytes, welche auf die Positionen der Levels innerhalb der Datei zeigen.... usw. ginge wohl weiter so für die nächsten 20 Seiten...Eben gibt es hierfür eine vernünftige Notation oder eine Art UML Sprache oder ähnliches?
Lg Ishildur
-
Für den Eigengebrauch dokumentiere ich Dateiformate i.d.R. in einer höchst einfach gehaltenen Notation mit an BASIC orientierten Suffix-Typsystem (& - char/1-Byte-Integer, % - short/2-Byte-Integer, # - long/4-Byte-Integer, $ - nullterminierter String, ! - 1-Byte-bool etc.). In deinem Fall sähe das so aus:
Header: <LevelCount%> LevelCount * [<LevelDescOffset#>] LevelDesc: ...Einem offiziellen Standard folgt das freilich nicht. Aber es funktioniert :p
-
Meistens besteht ein Dateiformat aus irgendwelchen Blöcken. Diese Blöcke sortiere ich, bennene sie und mache dann ein Inhaltsverzeichnis daraus. Jeder Block bekommt seinen Abschnitt und wir ausführlich dokumentiert, wie er aufgebaut ist und was damit gespeichert wird.
In einem zweiten Teil definiere ich dann die Reihenfolge dieser Blöcke und verwende dazu die EBNF-Syntax.
Ich denke, dass jeder, welcher einmal etwas mit Informatik zu tun hatte, das ganze dann auch nachvollziehen kann.
Grüssli
-
Ich habe schon häufiger gesehen, dass die Dateiformate mit C-(oder Pseudo-C)-Structs dokumentiert wurden. Kommt natürlich ein wenig auf die „Kundschaft“ an, aber die meisten Programmierer können damit was anfangen.
-
IDL wäre auch eine Möglichkeit, wobei das nahe dran ist, an .filmors Vorschlag.
