Konvention vor Dokumentation Convention over documentation— —Robert Bruckbauer
Im Prinzip COD geht im Wesentlichen um die Vermeidung von Dokumentation. Was durch Teile von Code (z.B. durch kommentierte Klassen oder Skripte) bzw. einem code-nahen Artefakt (z.B. eine Spezifikation oder Konfiguration) ausreichend gut beschrieben wird, muss im Wiki nicht mehr zusätzlich in Prosa beschrieben werden. Das Wiki stellt für die vom Team veröffentlichten Artefakte mehr eine Art Navigationshilfe für diese spezielle Art der Dokumentation dar.
Das Prinzip COD basiert auch auf der Konvention, dass Titel von Seiten aus dem Wiki sich direkt im Code oder einem Testplan wiederfinden, z.B. als Namensraum oder als Teil des Namens einer Klasse oder eines Skripts.
- Den Baustein Domain nutzen wir zur Gruppierung von Diensten. Der Titel findet sich beispielsweise im Namen einer Gitlab-Gruppe wieder.
- Den Baustein Service gibt einem Dienst einen eindeutigen Namen und beschreibt seine Funktion. Der Titel findet sich im Namen der Implementierungsklasse wieder.
- Der Baustein Event gibt einem Nachrichtenobjekte einen eindeutigen Namen und beschreibt seinen Inhalt. Der Titel findet sich im Namen der Implementierungsklasse wieder. Bei der Verwendung von Schemaspezifikationen wie beispielsweise Apache Avro ist es der Titel gleichzeitig der Name der Schemadatei. Erst dort sehen wir alle Details, z.B. Typ oder Einschränkungen (engl. constraints) einer fachlichen Eigenschaft.
- Der Baustein Entity gibt einem Informationsobjekte einen eindeutigen Namen und beschreibt seinen Inhalt. Der Titel findet sich im Namen der Implementierungsklasse wieder. Bei der Verwendung von Schemaspezifikationen wie beispielsweise XSD ist es der Titel gleichzeitig der Name der Schemadatei. Erst dort sehen wir alle Details, z.B. Typ oder Einschränkungen (engl. constraints) einer fachlichen Eigenschaft.
- Den Baustein Layout gibt einem Teil der Bedienoberfläche einen eindeutigen Namen und beschreibt seinen Aufbau. Der Titel findet sich im Namen der Implementierungsklasse wieder.
Wenn wir diese einfach umzusetzenden Regeln berücksichtigen, dann brauchen Leser keine spezielle Dokumentation mehr, um einen Dienst oder ein Objekt mit der technischen Lösung zu verknüpfen. Der Name allein reicht. Er ist der ideale Einstieg in die Implementierung.
Das Prinzip COD hilft auch bei der Durchsetzung der gemeinsamen Sprache im Team.