Was gehört alles in eine richtige Dokumentation?

[MaBuSE]

Zitat von Furtbichler:

Also, ich würde mal sagen, der Name 'SetEnabledRec' ist Schrott. Im Clean-Code sollte er so heißen (z.B.):
SetEnabledOfChildControlsOnForm(aForm : TComponent; aParentControl : TControl; aValue : Boolean); Wozu also jetzt noch Kommentare?

Ich möchte dazu nur folgendes sagen:

1. Hat r2c2 das in seinem sehr ausführlichen Beitrag schon wirklich nett erklärt.
2. In Deinem Namen nicht erkennbar ist, dass rekursiv die Eigenschaft Enabled aller untergeordneten Elemte gesetzt werden.
3. Habe ich geschrieben, warum das so ist, und ich auch nicht glücklich damit bin.
4. Werden die Kommentare zur Erstellung der Dokumentation verwendet.
   Und ich bin immer noch der Meinung, dass in der Beschreibung einer API auch eindeutige Funktionen dokumentiert werden sollten.
   z.B. die Funktion abs()-> http://docwiki.embarcadero.com/Libra.../de/System.Abs

[Furtbichler]

...Hier stand der Beginn einer kleinen Auseinandersetzung, der jedoch von MaBuSe per PN im Keim erstickt wurde, weswegen das auch nicht hierhin gehört...

Ich fand es nur lustig, das r2c2's (korrekte) Aussage, sprechende Namen seien besser als Kommentare neben dein Paradebeispiel schlechter Nomenklatur zu stellen. Ich meine, das muss Dir doch selbst aufgefallen sein, das der Name ähem.. du weisst schon. Auto-an-Wand.

Übrigens, falls es dich interessiert: Ein Methodenname darf gerade nicht den Algorithmus ('Rekursiv') wiederspiegeln, sondern kurz und knapp erklären, was die Methode anstellt. 'SetEnabledRec' ist Schrottungenau, 'SetEnabledStateOfChildControls' nicht. Ob das rekursiv, iterativ oder sonst was ist, ist irrelevant. Wir können natürlich auch richtig albern werden, und das Teil
'SetEnabledStateOfChildAndTheirChildsAndTheirChild sAndSoOnControls' nennen, aber -hey- WTF.

Eine API zu dokumentieren, ist notwendig und vollkommen unabhängig von meinem Einwand (ich schrieb eigentlich nichts davon).

WEnn Du deinen API-Funktionen, oder wer auch immer die so genannt hat, einfach aussagekräftige Namen gibst, wird eine Dokumentation schnell überflüssig. Das merkst Du daran, das Du für die Beschreibung der Methode fast genau die Worte verwendest, die im Namen der Methode selbst stecken:

Delphi-Quellcode:

// Creates a Form of type aFormClass
procedure UIManager.CreateForm(aFormClass :TFormClass)

Es gibt Kollegen, die sich weigern das so hinzuschreiben. Weil es so einfach nur kreuzdämlich ist. Und eine Methode nur um des Kommentieren willens zu kommentieren, erinnert mich an die Schildbürger.

Dessenungeachtet sind Konstrukte wie dieses 'Ich setze Enabled gleich für alle Childcontrols' eigentlich kein Fall für eine API, denn eine API soll ja nur die Basisfunktionen bereitstellen und keine Superdupersonderichmachdasallesfürdich-Funktionen. Aber das steht auf einem anderen Blatt.

--- und hier stand auch noch überflüssiges Zeugs---