Javadoc, was gehört rein?

[Kaffeebohne]

Hallo Leute,

wie ist das mit dem Dokumentieren von Klassen. Werden auch Private und Protected Sachen dokumentiert, oder nur die Public Sachen?

 

[SamHotte]

Protected würde ich auf jeden Fall auch dokumentieren, denn wenn jemand anders deine Klassen erweitern können soll, dann sollte er wissen, was da passiert.

Private ist geschmackssache - oft kann es helfen zu wissen, was eine Methode macht - insbesondere, wenn es eine Weile her ist, dass sie implementiert wurde. Und wenn du Eclipse einsetzt, sind die Javadoc-Kommentare beim Aufrufen deiner privaten Methoden extrem hilfreich.

 

[Kaffeebohne]

Hmm,

okay danke SamHotte. Was ist denn üblich, also ich meine im Business?

 

[SamHotte]

Kommt drauf an -- meistens Vorgaben in der Art "alles ist fachgerecht zu kommentieren", verbunden mit der Tatsache, dass dafür keine Zeit zur Verfügung gestellt wird

 

[Wildcard]

Im Business soll sowieso alles dokumentiert sein, da man im Team arbeitet. Selbst wenn man alleiniger Verantwortlicher für ein Projekt ist, kann es ja auch sein das diese Aufgabe mal jemand anders übernimmt. Daher immer alles dokumentieren.
Damit macht man sich übrigens auch selbst das Leben leichter :wink:

 

[AlArenal]

Ich dokumentiere alles. Selbst wenn den Code nie wer anders zu Gesicht bekommen sollte, möchte auch ich in absehbarer Zeit noch wissen, was ich bei dem Code gedacht habe und mit welchem "Vertrag" ich ihn ausgestattet habe.

 

[Kaffeebohne]

Okay, sollte

Und wie siehts bei euch aus? Mal erlich (Denke mal ihr macht das auch beruflich)

 

[Wildcard]

Ich dokumentiere jede Methode, und wo erfordlich auch noch den Quelltext.

 

[Caffè Latte]

Hi,

im JavaDoc dokumentiere ich nur, um wass es grundlegend geht, also z.B. welche Parameter die Methoden haben, was sie zurückliefern etc. pp.

Im Quelltext selbst kommentiere ich immer das, was erklärungsbedürftig ist; z.B. bei "case x, case y ...", was denn Fall x und was Fall y ist .

BTW: ganz früher sollte ich mal in einem Projekt mitarbeiten. Die Firma hatte ein ganzes Framework mit endlos vielen Klassen im Laufe der Zeit aufgebaut. Es war aber nichts, rein gar nichts dokumentiert. Nache einer Woche gab ich auf ...

 

[me.toString]

Also ich mache JavaDoc-Kommentare für alle Methoden - auch die privaten. Da stehen allerdings keine Romane drin (es sei denn, die Methode macht so was super tolles und unbedingt erwähnenswertes), sondern nur ein Kurztext und die Parametererklärungen. Im Code selber schreibe ich dann auch noch jede Menge Zeugs rein. Ich hatte es schon, dass die Hälfte der Datei Kommentare waren ... :wink:
Ich hatte auch schon mal die "Freude" Fremdcode ohne jegliche Dokumentation zu bearbeiten ... die Zeit die man da reinsteckt, um das zu verstehen, ist meine Meinung nach deutlich höher als die Zeit, die man benötigt um eine ordenltiche Doku zu erstellen.

 

[Gast]

Das schlimmste was es gibt, ist schlecht dokumentierter, oder gar nicht dokumentierter Quellcode. Musste mich auch mal in nicht dokumentierten Quellcode einarbeiten und dazu war das Programm auch noch total unübersichtlich geschrieben. Anfangs dachte ich noch, das es ja gut sei, das der Programmierer noch in der Firma ist, nachdem er sich aber selbst auch nicht mehr ausgekannt hat, blieb die ganze Arbeit an mir hängen. Als ich dann immer ärgerlicher wurde und ihn darauf ansprach, was er da für einen Blödsinn verzapft hat, hat er nur blöd gelacht.

In der Anfangszeit meiner Programmierung habe ich auch nur wenig dokumentiert, aber nachdem ich das erlebt habe, dokumentiere ich wirklich jede Kleinigkeit.