Zum Inhalt

Dokumentation

Verwende US Englisch für Kommentare (CGC16001) recommendation level 1

Verwende US Englisch für Dokumentation (CGC16002) recommendation level 1

Dokumentiere alle von außerhalb verfügbaren Typen und Members (CGC16003) recommendation level 2

Alle Typen und Members, die von außerhalb des Programmes, aber auch außerhalb Namespaces, Paketen oder Typen innerhalb des Programmes erreichbar sind, sollten mit, für die jeweilige Sprache standardisierte Style, dokumentiert werden. Auf diesen Weg können andere Entwickler den Verwendungszweck und die Verwendung verstehen, ohne den eigentlichen Code zu kennen.

Außerdem ist es möglich, mit entsprechenden Tools, eine professionell aussehende Dokumentation zu erstellen.

Schreibe Dokumentation für andere (CGC16004) recommendation level 2

Dokumentation sollte für Nutzer geschrieben werden, die den dahinterstehenden Code nicht kennen. Sowohl der Verwendungszweck als auch die Verwendung sollte klar erklärt werden, um die bestmögliche Verwendung sicherzustellen.

Vermeide Inline-Kommentare (CGC16005) recommendation level 2

Wenn Inline-Kommentare nötig sind, sollte es in betracht gezogen werden, ob es besser wäre, den betroffenen Code in eine eigene Methode mit einem aussagekräftigen Namen auszulagern.

Verwende keine Kommentare, um zukünftige Aufgaben festzuhalten (CGC16006) recommendation level 2

Es ist gut, wenn Arbeit, die aktuell nicht erledigt werden konnte, festzuhalten, allerdings sollte dies in einem Projektmanagementsystem erfolgen. Die Verwendung von TODO-Kommentare ist zwar auch eine Möglichkeit, allerdings wird in der Praxis nicht oder nur selten nach solchen Kommentaren gesucht und gelöst.

Eine weitere Möglichkeit ist eine Kombination aus beiden. Ein Ticket in dem jeweiligen Projektmanagementsystem anlegen und ein dazugehöriges TODO-Kommentar anlegen und in diesem das Ticket referenzieren.

Schreib Kommentare um komplexe Algorithmen oder Entscheidungen zu erklären (CGC16007) recommendation level 1

Kommentare sollten sich auf das Was? und Warum? konzentrieren, statt auf dem Wie?. Die Statements sollten nicht Zeile für Zeile erklärt werden, sondern es sollte das Ziel erklärt werden, und weshalb genau diese Lösung verwendet wurde, wenn sie einer offensichtlicheren vorgezogen wurde, z. B. welche Probleme dadurch vermieden werden.


Letztes Update: 2021-09-26
Zurück zum Seitenanfang