Hallo, ich suche einen Rat aus der Praxis was Dokumentation von Softwareprojekten angeht. Wie könnte Eurer Meinung nach eine einfache Dokumentation für eine SW aussehen, die in C++, also in Klassen und weitestgehend objektorientiert, geschrieben wurde. Anforderung sollte sein, dass die Zeit für die Dokumentationserstellung nicht zuviel Zeit in Anspruch nimmt und möglich einfach sein sollte. Meine Recherche brachte zwar viele Ideen, aber so recht überzeugt bin ich von den Lösungen nicht. Auch habe ich das Gefühl, wenn der Entwickler nicht gewohnt ist mit einer Dokumentation a la UML zu arbeiten, dann braucht er recht viel Zeit für die Doku. Meine Idee war ein einfach gehaltenes Formblatt, dass eine kurze Beschreibung der Klasse hat, die Variablen beschreibt (public und private), die Zugriffsfunktionen und kurz den Algorythmus. Allerdings bekomme ich immer Schwierigkeiten wenn allgemeine Klassen wie z. B, Standardklassen aus VC++ verwendet werden (mit Wizard), da dort der Sourcecode in ein vorgefertigtes Objekt geschrieben wird. Dort ist die Erstellung der Doku dann langwieriger als das tippen des Codes. Da dieses Problem bestimmt schon 1000de von Personen vor mir gehabt haben müssen, muß es doch eine einfache Lösung geben. Und wenn es UML ist, dann muss ich es halt lernen damit umzugehen. Bin für jeden Tipp dankbar.
Das macht heutzutage keiner mehr manuell. Wir verwenden bei uns: http://www.stack.nl/~dimitri/doxygen/ Also such mal Dokumentationssoftware. Es gibt viel kostenloses und auch etliches kostenpflichtiges. Manuell war gestern.
Der Sourcecode ist die Dokumentation. Wenn der Source so ist, dass man ihn erst noch aufwändig dokumentieren muss, was dieses oder jenes denn genau tut, dann ist etwas faul. Ansonsten, was doch zu dokumentieren ist, möglichst viel und automatisch erzeugen. Alles was in separaten Dateien steht ist Müll, da es über kurz oder lang nicht mehr syncron mit dem realen Source ist.
Hi
>Der Sourcecode ist die Dokumentation.
Das würde ich als "Der Sourcecode mit Kommentaren ist die
Dokumentation." unterschreiben. Insbesondere wenn man sich in fremden
Code einließt gehört zu jeder Funktion (bzw. Methode) dazu was sie
macht wenn es nicht gerade eine triviale Funktion ist. Wenn ich erst
100 Zeilen Quelltext lesen muss, nur um herauszufinden was die Funktion
macht, dann hat der Ersteller was flasch gemacht.
Matthias
Du verwechselt was und wie. Was eine Funktion/Methode macht lässt sich im allgemeinen bestens durch gut gewählte Namen kommunizieren. (Nein, strcat und strstr sind z.B. keine gut gewählten Namen. find_substring oder sowas wäre besser gewesen für strstr). Wenn innerhalb einer Funktion noch dokumentiert werden muss, wie der Code funktioniert, dann ist der Code unbrauchbar. Ausnahmen gibts natürlich.
Hi Bei C mag das ja noch stimmen. Bei Sprachen die Funktionen überladen können wird das schon schwierig. Da gibt es dann 20 Varianten von drawRect die alle eine andere Parameterliste haben. Soll jetzt jede Funktion einen selbsterklärenden Namen haben kommen da solche Ungetüme wie drawRectWithScaledBitmapAsSourceWithLinearFiler(...) bei raus. Na dann doch lieber /** * Draws a rectangle into this bitmap with anothor bitmap as source * image and with a linear filter for scaling. * * @param sourceBitmap The bitmap to read from * @param .... */ void drawRect(...) Matthias
Naja, was für zusätzliche wertvolle Informationen man durch den Kommentar "The bitmap to read from" noch über den Parameter sourceBitmap erhält, ist mir da jetzt aber ziemlich schleierhaft. Wer Funktionen 20 mal überlädt verdient ehrlich gesagt auch Prügel. Ich liebe nichts mehr, als anhand von Parameterlisten rauszufinden, welchen Overload ich jetzt aufrufen soll. .NET lässt grüssen. Ist allerdings bis zu einem gewissen Grad alles eine Ermessensfrage.
Hi Das ist wirklich Ansichtssache. Aber der Unterschied zwischen einer Klasse mit 200 unterschiedlich benamten Methode und einer mit 20 Methoden die 10 fach überladen sind ist einfach das die Suche nach der passenden Methode schneller geht (sinnvolle Überladung vorrausgesetz). Suche in einer Baumstruktur ist nunmal effizienter als Suche in einer flachen Liste. Matthias
> void drawRect(...) drawRect() ist schon der erste Fehler. Warum nicht drawRectangle(), oder, alternativ, wenn man (wie ich) die Camel-Case-Schreibweise nicht mag (und es auch genügend psychologische Untersuchungen gibt dass eine solche Schreibweise Mist ist) draw_rectangel()? Dann kann man sich auch diesen Kommentar > Draws a rectangle [...] schon sparen. Denn es ist einfach Unsinn, in einem Kommentar zu schreiben, dass drawRect() in Wirklichkeit "Draw Rectangle" heißt. Und weiter, in diesem konkreten Beispiel. Wenn drawRectangel() eine Bitmap skaliert zeichnet, ist dann der Name drawRectangle() überhaupt noch korrekt? Wäre in diesem Fall drawScaledBitmap() / draw_scaled_bitmap() nicht der korrekte Funktionsname? Über Parameternamen und Überladung hat Barli schon alles wesentliches geschrieben.
> und es auch genügend psychologische Untersuchungen gibt dass eine
solche Schreibweise Mist ist
Rein aus Interesse : Was sind denn die Begründungen für diese Aussage ?
Es gibt Leute, die bekommen Hautausschlag, wenn ihnen jemand was von der "ungarischen Notation" erzählt. Die beschreibt nicht nur das Voranstellen eines Typbezeichnerkürzels als Präfix, sondern auch die zusammengezogene Schreibweise mit Großbuchstaben. Der Hautausschlag ist vermutlich politisch-religiöser Natur und daher nicht wirklich begründbar.
Ich weiss nicht, ich bevorzuge weder die eine noch die andere Variante. Normalerweise verwende ich diejenige, die sich in der jeweiligen Umgebung (wieso auch immer) als Standard durchgesetzt hat, d.h. schreibe ich Java-Code, dann schreibe ich doSomething(int foo); schreibe ich Ruby-Code, dann schreibe ich def do_something(foo)
Hi Nur was tut man in C/C++. In C gibt es Bibliotheken sowohl mit camel case Schreibweise als auch mit '_' als Trenner. Wichtig ist nicht welche Schreibweise man verwendet (entweder man bekommt eine Vorgabe oder verwendet seinen persönlichen Favoriten) sondern dass man einen Stil dann konsequent beibehält. Ich persönlich ziehe, psychologische Untersuchungen hin oder her, camel case vor. Matthias
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.