Im Fokus der objektorientierten Programmierung steht die Wiederverwendung von schon vorhandenem Code und auch dessen Erweiterbarkeit. Dies ist jedoch nur dann möglich, wenn die Funktion des schon vorhandene Code auch schnell erfasst und verstanden werden kann.
Hierzu ist die Dokumentation von Code essentiell und sollte auch nach einem Standart durchgeführt werden. Selbstverständlich sollte hierbei sein, dass eine Klasse in Ihrem Header kurz und knapp beschrieben wird. Dazu gehören die verwendeten Parameter wie auch die bereitgestellten Methoden.
Auch sollte der Hinweis über den Entwickler des Code und der Versionsnummer vorhanden sein, da sich Code, vor allem unter der Einwirkung mehrerer Entwickler verändern kann. Primär steht hier die Erweiterung der Klasse, da fertig implementiere Methoden in der Regel nicht mehr „angefasst werden sollten“, so sonst möglicherweise Abhängigkeiten zerstört werden.
Tags
@author, mit diesem Tag sollte der oder die Entwickler der Klasse oder des Interfaces gekennzeichnet werden, damit man bei bedarf auch Rücksprachen halten kann.
@version, diese Tag gibt die fortlaufende Version an, damit man die Veränderung des Codes der Klasse oder des Interfaces nachvollziehen kann und möglicherweise bei Problemen auch mit der vorhergehenden Version vergleichen kann.
@param, gibt an, welche Parameter die Methode oder Konstruktoren konsumiert und von welchem Typ diese sind. Das hilft dem Entwickler ungemein beim Verständnis, wenn er diese Methode aufruft, da er dann angezeigt bekommt, welche Parameter konsumiert werden und von welchem Typ diese sind.
@return, ist analog zum Tag @param, nur dass dieser den Rückgabewert angibt und dessen Typ. Somit weiss der Entwickler gleich, welchen Typ er unter der Verwendung der Methode zu erwarten hat.
@exception, kann es möglicherweise zu einem unerwarteten Problem kommen, so kann diese mit einem Try and Catch Block abgefangen werden. Hierzu wirft die Methode dann eine Exeption, also eine Ausnahme. Diese Ausnahme sollte im Code gekennzeichnet und ausführlich beschrieben werden.
@throws, wie bei der Exeption, kann auch ein fehler „geschmissen“ werden. Dieser wird dann mittels Throws gekennzeichnet.
Auch gibt es noch speziellere Tags wie: @see @since @deprecated.