mikrocontroller.net

Forum: Offtopic Dokumentation von Softwareprojekten


Autor: Beda (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Dieter (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Unbekannter (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Μαtthias W. (matthias) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Autor: Bartli (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Μαtthias W. (matthias) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Autor: Bartli (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Μαtthias W. (matthias) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Autor: Unbekannter (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
> 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.

Autor: Bartli (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
> 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 ?

Autor: Rufus Τ. Firefly (rufus) (Moderator) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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.

Autor: Bartli (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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)

Autor: Μαtthias W. (matthias) Benutzerseite
Datum:

Bewertung
0 lesenswert
nicht lesenswert
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

Bitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail, Yahoo oder Facebook? Keine Anmeldung erforderlich!
Mit Google-Account einloggen | Mit Facebook-Account einloggen
Noch kein Account? Hier anmelden.