Doppeldeutige Dokumentation

Was man aus einem Glückskeks lernen kann...

Mittwoch 15 Mai 2013 at 5:46 pm.

Vor einigen Tagen habe ich mittags asiatisch gegessen. Das Essen war gut, aber in Erinnerung geblieben ist mir der Spruch im Glückskeks. Ich weiß, dass diese Sprüche gerne allgemein gehalten sind und jeder etwas hinein interpretieren kann, aber dieser Spruch war sehr konkret und doch extrem doppeldeutig:

Es stehen Veränderungen vor der Tür. Lass sie ruhig zu.

Ich hab diesen Spruch mehrmals gelesen, bis mir die Doppeldeutigkeit aufgefallen ist.

Das hat mich dann an die Dokumentation von Quelltexten erinnert. Manchmal sind es ganz banale Informationen, die man nicht braucht

int i = 5;  // Zähler initialisieren

oder die Information ist so verschlüsselt, dass man nicht weiß was man damit anfangen soll

return CheckCodeForSpecialSymbol(code); // prüft, ob code die Anforderung erfüllt

Dieser Spruch aus dem Glückskeks erinnert mich nun daran, dass man Erläuterungen möglichst eindeutig formulieren muss. Wenn das schwerfällt, dann ist das ein Zeichen dafür, dass man selbst nicht versteht, was dort passiert. Und man sollte später noch mal drüber schauen, ob der Text wirklich verständlich ist.

In dem Sinne lassen wir die Tür doch besser nicht zu, oder ?

Christof