AGB  ·  Datenschutz  ·  Impressum  







Anmelden
Nützliche Links
Registrieren

Software-Dokumentation

Ein Thema von Gentleman · begonnen am 17. Okt 2009 · letzter Beitrag vom 18. Okt 2009
Antwort Antwort
Gentleman

Registriert seit: 29. Sep 2004
302 Beiträge
 
Turbo Delphi für Win32
 
#1

Software-Dokumentation

  Alt 17. Okt 2009, 17:17
Hallo Delphi-Gemeinde!

Ich habe im Zuge meines Studiums die Aufgabe bekommen, eine Software zu entwicklen. Dazu soll ich eine Dokumentation schreiben, am besten so, dass auch später andere Entwickler etwas damit anfangen können.
Nun habe ich schon etwas im Internet recherchiert aber leider keine konkreten Informationen finden können. Ich suche eigentlich soetwas wie eine kleine Anleitung zum Thema Software-Dokumentation. Da sich hier ja nun schon einige erfahrene Entwickler finden, wollte ich nun einfach mal direkt fragen.

Wie schreibt ihr solche Dokumentationen, einfach so "frei Hand" oder gibt es dazu vielleicht irgendwelche Vorlagen, an denen man sich orientieren könnte? Und was soll eigntlich in so einer Dokumentation stehen, was ich wichtig für Entwickler, was ist wichtig für die Anwender?

Ich bin für alle Tipps dankbar, die mir da weiterhelfen könnten!

Vielen Dank!

Gruß
Lennard
  Mit Zitat antworten Zitat
Hansa

Registriert seit: 9. Jun 2002
Ort: Saarland
7.554 Beiträge
 
Delphi 8 Professional
 
#2

Re: Software-Dokumentation

  Alt 17. Okt 2009, 18:36
Stelle dir mal zuerst die frage, was du selber von einer "dokumentation" erwartest. Beispiele gibt es in jedem handbuch.
Gruß
Hansa
  Mit Zitat antworten Zitat
Benutzerbild von rweinzierl
rweinzierl

Registriert seit: 22. Mär 2005
97 Beiträge
 
#3

Re: Software-Dokumentation

  Alt 17. Okt 2009, 18:43
Hallo

Wenn es darum geht das sich andere Entwickler zurechtfinden dann empfehle ich die Dokumentation im Quellcode !

Mit Programmen wie pasdoc ... kannn aus diesen Kommentaren eine Dokumentation erstellt werden.

mfg


Reinhold




--------------
www.ithof.de Arzneimitteldokumentation
  Mit Zitat antworten Zitat
Benutzerbild von Phoenix
Phoenix
(Moderator)

Registriert seit: 25. Jun 2002
Ort: Hausach
7.552 Beiträge
 
#4

Re: Software-Dokumentation

  Alt 18. Okt 2009, 09:18
Zitat von Gentleman:
Ich habe im Zuge meines Studiums die Aufgabe bekommen, eine Software zu entwicklen. Dazu soll ich eine Dokumentation schreiben, am besten so, dass auch später andere Entwickler etwas damit anfangen können.
Quellcode-Dokumentation wurde schon angesprochen.
Beachte dabei aber bitte folgendes: Versuche, keine Redundanten Informationen zu dokumentieren.
In einem 5-Zeilen Dokumentationsheader vor einer Funktion erst nochmal den Namen, den Rückgabetyp und die Parameter samt ihrem Namen aufzuführen und mit maximal 2 bis drei 3 worten zu ergänzen ist keine Dokumentation. Der Nachteil liegt auf der Hand: Änderst Du die Methode und vergisst diese 'Doku' anzupassen (Du glaubst gar nicht, wie schnell man sich sagt 'Das mach ich nachher' und macht es dann doch nicht), dann ist die Doku nicht nur ein wenig veraltet, sondern sogar falsch. Wer sich dann daran hält hat ein Problem und muss erst nachforschen.

Also wenn Doku im Quellcode, dann nur wichtige Dinge wie 'Warum' wurde das hier so gelöst.

Der beste Quellcode spricht für sich. Also anstelle von idxCtr bitteschön den Namen IndexCounter verwenden, eine Funktion nicht Person.DelAll sondern Person.DeleteRecordWithAllDependencies nennen.
Du glaubst gar nicht, wie etwas längere, treffendere Namen den Quellcode vereinfachen.

ABER: Ein anderer Entwickler lernt am besten aus Beispielen.

Wenn Du diese Software von null an entwickelst, dann gewöhne Dir gleich hierbei an, Unittests zu schreiben. (Test Driven Development ist das Stichwort).

Das hat mehrere Vorteile:
Andere Entwickler können die Tests als Beispiel nehmen. Denn hier wird die Klasse verwendet um etwas zu tun. Und wie das getan wird ist im Test schön einfach gezeigt. Eine bessere Doku für Entwickler gibt es nicht, insbesondere nicht, wenn der Test sauber benannt ist: TestDeletePerson oder TestRenamePerson. Der zweite Vorteil: Änderst Du etwas so, dass es einen Seiteneffekt hat, dann wird Dir ein fehlschlagender Test zeigen, dass so etwas passiert ist. Änderst Du etwas so, dass sich eine Methode ändert, kompiliert das 'Beispiel' nicht mehr. Das heisst, Du hast entweder etwas nicht weit genug bedacht, oder der alte Test ist durch neue Anforderungen weggefallen oder musste sich auch ändern.

Ich empfehle Dir vielleicht vorher einen Blick in das Buch 'Clean Code' von Robert C. Martin zu werfen http://www.amazon.de/exec/obidos/ASIN/0132350882/delphipraxis-21, da steht vieles dazu drin, wenn auch nicht auf die Dokumentation bezogen sondern allgemein über sauberen und wartbaren Quellcode. Imho sollte sich niemand Informatiker Schimpfen dürfen, der das nicht gelesen hat
Sebastian P.R. Gingter
不死鳥 Visit my Blog.
Do not argue with an idiot. They lower you to their level and then try to beat you with experience.
  Mit Zitat antworten Zitat
Gentleman

Registriert seit: 29. Sep 2004
302 Beiträge
 
Turbo Delphi für Win32
 
#5

Re: Software-Dokumentation

  Alt 18. Okt 2009, 15:15
Zitat:
Wenn es darum geht das sich andere Entwickler zurechtfinden dann empfehle ich die Dokumentation im Quellcode !
Ntürlich könnte ich im Quellcode dokumentieren, klingt auch durchaus sehr sinnvoll, allerdings wollte ich die Dokumentation schon gerne gesondert verfassen, d.h. in soetwas wie einem "Handbuch".
Der Grund ist, dass ich zwar auch möglicherweise mal ein anderer Entwickler in dem Code zurecht finden soll, aber es geht mir auch zu einem großen Teil darum, meine Arbeit zu dokuemtieren, da ich das Programm dann auch abgeben werde.


Zitat:
Stelle dir mal zuerst die frage, was du selber von einer "dokumentation" erwartest. Beispiele gibt es in jedem handbuch.
Die Frage habe ich mir natürlich auch schon gestellt, allerdings ist es natürlich immer schwierig sich zu überlgen, was man erwartet, wenn man noch gar keine Erfahrungen in diesem Themengebiet hat.
Was wäre denn z.B. ein Handbuch, in dem ich dazu nährere Informationen finden könnte?


Zitat:
ABER: Ein anderer Entwickler lernt am besten aus Beispielen.
Das klingt logisch. Beispiele könnten natürlich auch in meiner Dokumentation eine wichtige Rolle Spielen. Ebenso wie der suaber strukturierte Quelltext, das scheint mir natürlich die Grundlage des Ganzen zu sein.

Gibt es denn z.B. so etwas wie Gundregeln, z.B. was dokumentiere ich eigentlich, was nicht? Oder was muss ich genauer erläutern und was ist selbsterklärend?

Gruß
Lennard
  Mit Zitat antworten Zitat
Themen-Optionen Thema durchsuchen
Thema durchsuchen:

Erweiterte Suche
Ansicht

Forumregeln

Es ist dir nicht erlaubt, neue Themen zu verfassen.
Es ist dir nicht erlaubt, auf Beiträge zu antworten.
Es ist dir nicht erlaubt, Anhänge hochzuladen.
Es ist dir nicht erlaubt, deine Beiträge zu bearbeiten.

BB-Code ist an.
Smileys sind an.
[IMG] Code ist an.
HTML-Code ist aus.
Trackbacks are an
Pingbacks are an
Refbacks are aus

Gehe zu:

Impressum · AGB · Datenschutz · Nach oben
Alle Zeitangaben in WEZ +1. Es ist jetzt 16:25 Uhr.
Powered by vBulletin® Copyright ©2000 - 2022, Jelsoft Enterprises Ltd.
LinkBacks Enabled by vBSEO © 2011, Crawlability, Inc.
Delphi-PRAXiS (c) 2002 - 2021 by Daniel R. Wolf