Schwarz auf weiß

Aussagekräftige Variablen- und Methodennamen, gut strukturiert und damit gut lesbar: So soll Quelltext sein. Vor allem aber soll er selbsterklärend sein. Die Zeiten, in denen der Zweck jeder Variablen mit einem Kommentar erklärt wurde, sind doch hoffentlich vorbei, oder? Gerade aber bei Schnittstellen sollte die Bedeutung und Aufgabe der Methoden dokumentiert sein – so ausführlich wie nötig. Welche Parameter gehen hinein, welchen Rückgabewert muss der Nutzer der Schnittstelle erwarten? Auch gibt es viele zusätzliche Informationen, die nicht so leicht aus dem Code herauszu­lesen sind. Warum wurde diese spezielle Implementierung gewählt? Warum heißt die Variable entgegen aller Codierrichtlinien genau so und darf auch nicht umbenannt werden? Warum schindet ein Timer an der Stelle eine Sekunde Zeit?