Das Prinzip COD

Conven­tion over docu­mentation

Konven­tion vor Doku­mentation

Robert Bruckbauer

Im Prinzip COD geht im Wesent­lichen um die Ver­meidung von Doku­mentation. Was durch Teile von Code (z.B. durch kommen­tierte Klassen oder Skripte) bzw. einem code-nahen Arte­fakt (z.B. eine Spezifi­kation oder Konfi­guration) aus­reichend gut beschrie­ben wird, muss im Wiki nicht mehr zusätz­lich in Prosa beschrie­ben werden. Das Wiki stellt für die vom Team ver­öffent­lichten Arte­fakte mehr eine Art Navi­gations­hilfe für diese spezi­elle Art der Doku­mentation dar.

Das Prin­zip COD basiert auch auf der Kon­vention, dass Titel von Seiten aus dem Wiki sich direkt im Code oder einem Test­plan wieder­finden, z.B. als Namens­raum oder als Teil des Namens einer Klasse oder eines Skripts.

• Den Bau­stein Domain nutzen wir zur Grup­pierung von Diensten. Der Titel findet sich beispiels­weise im Namen einer Gitlab-Gruppe wieder.
• Den Bau­stein Service gibt einem Dienst einen ein­deutigen Namen und beschreibt seine Funk­tion. Der Titel findet sich im Namen der Imple­mentie­rungs­­klasse wieder.
• Der Bau­stein Event gibt einem Nach­richten­­objekte einen ein­deutigen Namen und beschreibt seinen Inhalt. Der Titel findet sich im Namen der Imple­mentie­rungs­­klasse wieder. Bei der Ver­wendung von Schema­­spezifi­kationen wie beispiels­weise Apache Avro ist es der Titel gleich­zeitig der Name der Schema­datei. Erst dort sehen wir alle Details, z.B. Typ oder Ein­schränkungen (engl. constraints) einer fach­lichen Eigen­schaft.
• Der Bau­stein Entity gibt einem Infor­mations­­objekte einen ein­deutigen Namen und beschreibt seinen Inhalt. Der Titel findet sich im Namen der Imple­mentie­rungs­­klasse wieder. Bei der Ver­wendung von Schema­­spezifi­kationen wie beispiels­weise XSD ist es der Titel gleich­zeitig der Name der Schema­datei. Erst dort sehen wir alle Details, z.B. Typ oder Ein­schränkungen (engl. constraints) einer fach­lichen Eigen­schaft.
• Den Bau­stein Layout gibt einem Teil der Bedien­oberfläche einen ein­deutigen Namen und beschreibt seinen Aufbau. Der Titel findet sich im Namen der Imple­mentie­rungs­­klasse wieder.

Wenn wir diese ein­fach umzu­setzen­den Regeln berück­sichtigen, dann brauchen Leser keine spezi­elle Doku­men­tation mehr, um einen Dienst oder ein Objekt mit der tech­nischen Lösung zu ver­knüp­fen. Der Name allein reicht. Er ist der ideale Ein­stieg in die Imple­men­tie­rung.

Das Prin­zip COD hilft auch bei der Durch­setzung der gemeins­amen Sprache im Team.