|
|
|
|
|
rtfm?
|
Wer professionell Programme schreibt dürfte das Problem nur zu gut kennen. Das Projekt ist fertig doch wirklich lust das Ganze zu dokumentieren hat keiner. 
Naja, dummerweise muss ich jetzt so etwas dokumentieren, aber ich habe so etwas noch nie gemacht. Vermutlich sollte ich mal einen solchen Kurs besuchen. 
Somit geht hier meine Frage an euch:
Wie dokumentiere ich ein Softwareprojekt richtig?
Reichen da ein paar Kommentarzeilen im Code?
Was für Methoden gibt es dafür?
|
|
|
|
|
|
|
|
|
|
|
Kommentare im Code sind schon während dem programmieren Pflicht  - für mich zumindest
Es kommt drauf an, wer das am Ende benutzten muss. Für jemanden der das ganze weiterentwickeln soll müssten Kommentare im Code ausreichend sein.
Für Benutzer des Systems/Programms müsste man die grundlegenden Funktionen erklären. Da sollte es schon eher ein kleines "How-To" sein, dass auch ein DAU damit klar kommt.
|
|
|
|
|
|
|
|
|
|
|
Sehr viel bringt schon eine sorgfältige Kommentierung des Codes (am besten vom Programmierer). Daraus kann man dann z.B. eine API automatisch generieren und mit erklärenden Texten versehen.
Bei Java nimmt man Javadoc, bei PHP PHPDoc. Bei anderen Sprachen kenn ich mich ned aus.
|
|
|
|
|
|
|
|
|
|
|
| | Zitat von v!pe
Für Benutzer des Systems/Programms müsste man die grundlegenden Funktionen erklären. Da sollte es schon eher ein kleines "How-To" sein, dass auch ein DAU damit klar kommt. | |
An eine Art Benutzerdokumentation/Anleitung habe ich auch schon gedacht. Werde ich auch machen, obwohl es selbsterklärend sein sollte.
Aber ihr wisst ja wie das ist... Als Programmierer weiss man immer was man darf und was nicht.
|
|
|
|
|
|
|
|
|
|
|
Bei PHP und anderen Sprachen gibt es gewisse Regeln, nach denen man Methoden beschreibt.
Bei Zend Studio zB werden dann auch gleich die benötigten Parameter, Eigenschaften und eine kurze Beschreibung bei der Benutzung einer Funktion als PopUp eingeblendet.
sieht zB so aus:
| |
| PHP: |
/**
* blablubb
*
* @access public
* @param string
* @return string
*/
|
|
|
|
|
|
|
|
|
|
|
|
ähem... und .NET?
> Müsste mal nach nem Plugin suchen oder so...
|
|
[Dieser Beitrag wurde 1 mal editiert; zum letzten Mal von K.I.F am 09.11.2006 15:08]
|
|
|
|
|
|
|
|
|
|
Sofern du .NET mit irgendeinem Visual Studio programmierst, hast du wunderschöne XML-Docs im Quelltext.
|
|
|
|
|
|
|
|
|
|
|
Dokumentieren sind was für Weicheier. 
|
|
[Dieser Beitrag wurde 1 mal editiert; zum letzten Mal von SirSiggi am 09.11.2006 15:13]
|
|
|
|
|
|
|
|
|
| | Zitat von [mathu]
Sofern du .NET mit irgendeinem Visual Studio programmierst, hast du wunderschöne XML-Docs im Quelltext. | |
Echt? Wo?
|
|
|
|
|
|
|
|
|
|
| | Zitat von SirSiggi
Dokumentieren sind was für Weicheier. | |
Joa, wer sich die Mühe macht seine Source zu dokumentation, hat echt zuviel Zeit.
|
|
|
|
|
|
|
|
|
|
|
It was hard to code, it should be hard to understand!
Hat nem Komolitonen von mir nen dicken Einlauf beim Numerische Mathematik-Praktikum eingebracht.
|
|
|
|
|
|
|
|
|
|
|
Quelltext kommentieren ist etwas für Menschen die definitiv viel zu viel Zeit haben.
Über die Dokumentation von Methoden / Funktionen brauchen wir uns nicht unterhalten, ein kleiner Kommentar über jeder Funktion sollte nicht zuviel Zeit kosten und kann bei einem Framework mit 1000+´Funktionen durchaus hilfreich sein.
Wenn ich im code allerdings sowas wie
if(AuthManager::IsAuthed($customer)) { // schaut ob der Benutzer eingeloggt ist
lese, muss ich leider kotzen.
|
|
|
|
|
|
|
|
|
|
|
| | Zitat von [mathu]
Sofern du .NET mit irgendeinem Visual Studio programmierst, hast du wunderschöne XML-Docs im Quelltext. | |
Mit NDoc kann man die dann noch wunderbar in noch schönere HTML-Dokumentationen umwandeln.
Jetzt müsstest du nurnoch sagen, obs ne User-Doku oder ne Entwickler-Doku sein soll  Weil die User-Doku sieht komplett anders aus (Im Grunde ist das ja eher das "Handbuch"). Als Entwickler-Doku reicht sicherlich die Ausgabe von NDoc.
|
|
[Dieser Beitrag wurde 1 mal editiert; zum letzten Mal von tr|Mork am 09.11.2006 17:44]
|
|
|
|
|
|
|
|
| |
| Code: |
i = 1; // weist i den wert 1 zu |
|
Documentation is like sex; when it is good, it is very, very good; and when it is bad, it is better than nothing.
|
|
|
|
|
|
|
|
|
|
|
| | Zitat von tr|Mork
| | Zitat von [mathu]
Sofern du .NET mit irgendeinem Visual Studio programmierst, hast du wunderschöne XML-Docs im Quelltext. | |
Mit NDoc kann man die dann noch wunderbar in noch schönere HTML-Dokumentationen umwandeln.
Jetzt müsstest du nurnoch sagen, obs ne User-Doku oder ne Entwickler-Doku sein soll Weil die User-Doku sieht komplett anders aus (Im Grunde ist das ja eher das "Handbuch"). Als Entwickler-Doku reicht sicherlich die Ausgabe von NDoc. | |
Beides.
|
|
|
|
|
|
|
|
|
|
|
| | Zitat von Meister Zopf
| |
| Code: |
i = 1; // weist i den wert 1 zu |
|
Documentation is like sex; when it is good, it is very, very good; and when it is bad, it is better than nothing. | |
i don't agree
|
|
[Dieser Beitrag wurde 1 mal editiert; zum letzten Mal von Netbeater am 09.11.2006 21:10]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| | Zitat von Netbeater
| | Zitat von Meister Zopf
| |
| Code: |
i = 1; // weist i den wert 1 zu |
|
Documentation is like sex; when it is good, it is very, very good; and when it is bad, it is better than nothing. | |
i don't agree | |
Richtig, nichts ist schlimmer als eine Doku die einen in die Irre führt. Irgendwann weiß man dann selbst nicht mehr ob man nun einfach nur bescheuert, oder schlicht unfähig ist. 
|
|
|
|
|
|
|
|
|
|
|
Für .NET gibts wohl nichts besseres als Innovasys DocumentX, ansonsten kann man sich da viel selbst zusammenbauen mit GhostDoc, NDoc bzw. Sandcastle (MS Ersatz für NDoc) und einem Programm, womit man eine Vorschau der Dokumentation direkt im Visual Studio hat. Da gibts 1-2, leider habe ich die Namen vergessen.
Aber im Quelltext dokumentieren ist mal wirklich so bei komplizierten Algorithmen notwendig.
|
|
|
|
|
|
|
|
|
|
|
| | Zitat von [DK]Peacemaker
Für .NET gibts wohl nichts besseres als Innovasys DocumentX, ansonsten kann man sich da viel selbst zusammenbauen mit GhostDoc, NDoc bzw. Sandcastle (MS Ersatz für NDoc) und einem Programm, womit man eine Vorschau der Dokumentation direkt im Visual Studio hat. Da gibts 1-2, leider habe ich die Namen vergessen.
Aber im Quelltext dokumentieren ist mal wirklich so bei komplizierten Algorithmen notwendig.
| |
ein beispiel bitte
|
|
|
|
|
|
|
|
|
|
|
Heapsort.
Btw. da oben fehlt ein "nur" im letzten Satz 
|
|
|
|
|
|
|
|
|
|
|
|
Naja ich denke bei vielen Algorithmen hängt das auch davon ab, wie man seine Variablen benennt. Wenn diese aussagekräftig sind, ist es wohl eher verständlich als wenn man nur zB. n,i,x,y,z hat.
|
|
|
|
|
|
|
|
|
|
|
Das ist auch so eine Sache, hab ich aber dank .NET kein Problem mit, da kriegt niemand nen Anfall, wenn die Variablen auch mal was länger sind.
Aber wichtig ist, nicht zu dokumentieren, was jetzt ein bestimmter Befehl macht, sondern warum man diesen Befehl braucht etc.
"Tauscht den ersten und letzten Eintrag"
Kann ich nichts mit Anfangen, weil ich nicht weiß, wieso.
|
|
|
|
|
|
|
|
|
|
|
| | Zitat von [DK]Peacemaker
Das ist auch so eine Sache, hab ich aber dank .NET kein Problem mit, da kriegt niemand nen Anfall, wenn die Variablen auch mal was länger sind.
Aber wichtig ist, nicht zu dokumentieren, was jetzt ein bestimmter Befehl macht, sondern warum man diesen Befehl braucht etc.
"Tauscht den ersten und letzten Eintrag"
Kann ich nichts mit Anfangen, weil ich nicht weiß, wieso.
| |
int durchlaufvariablediebiszweihunderthochzaehltumauchwirklichzweihundertdurchlaeufezuhaben=0;
while (durchlaufvariablediebiszweihunderthochzaehltumauchwirklichzweihundertdurchlaeufezuhaben<=200)
{
cout << "huhu nr." << durchlaufvariablediebiszweihunderthochzaehltumauchwirklichzweihundertdurchlaeufezuhaben << endl;
}
|
|
|
|
|
|
|
|
|
|
|
nene, Doku is ne verdammt wichtige Sache, sonst ist der Code einfach nicht vollständig! Das ist ein richtiger Kraus Systeme zu portieren oder zu erweitern, wenn man nicht weiß, was man machen muss. Und direkt nen Javadoc/PHPdoc/DTDdoc/XSLTdoc/whatever über nen Funktionskopf zu schreiben ist wohl keine verschwendete Zeit und bei direkter Implementation auch schnell gemacht (als es im Nachhinein zu machen). Interessanterweise, so habe ich festgestellt, dokumentieren die Leute, die auch eine ordentliche Planung vorzulegen haben. Dann geht das Produkt raus, die Doku ist da, alles fein und so weiter, das Produkt lässt sich gut vermarkten. Anders ist so ein Produkt eigentlich schon zum scheitern verurteilt (grob betrachtet). Ein Handbuch gehört auch zur Dokumentation !
Schonmal versucht nen Typo3 zum Laufen zu bringen, ohne etwas nachzulesen?
- gossi
|
|
|
|
|
|
|
|
|
|
|
|
Ich gehe oft hin und schreibe ein programm erst in kommentaren, oder pseudocode, und fuege dann funktionierenden code hinzu. Wenn dann alles so tut wie's soll, werden die kommentare ein wenig verfeinert, und schon ist es relatiev einfach eine halbwegs gute dokumentation anzulegen...
|
|
|
|
|
|
|
|
|
|
|
Ich hab noch nie Software dokumentiert, abgesehen von phpdocs... die allerdings auch nur dazu dienen den meisten IDEs den Typ des Rückgabewerts beizubringen.
Dokumentieren sollen Leute die zu blöd sind zum programmieren.
|
|
|
|
|
|
|
|
|
|
|
|
Dann setz mal nen Typo3 auf OHNE ne doku zu lesen, kannst dir ja schnell im Source alles zusammensuchen
|
|
|
|
|
|
|
|
|
|
|
|
wie bereits gesagt, dokumentieren sollen die Leute die zu blöd sind zum Programmieren. Diese Aussage widerspricht ja nicht der Tatsache, dass manche Software eine Dokumentation benötigt.
|
|
|
|
|
|
|
|
|
|
|
|
Deine Meinung kann ich absolut nicht nachvollziehen.
|
|
[Dieser Beitrag wurde 1 mal editiert; zum letzten Mal von TriggerTG am 12.11.2006 4:02]
|
|
|
|
|
|
| Thema: Dokumentation ( rtfm? ) |
![[Dicope]](./avatare/drkleiner.gif)
![[dk]peacemaker](./avatare/[dk]peacemaker.gif)
