auch wenn es sich bei mir weniger um die direkte Hilfe bei einer Hausaufgabe geht möchte ich hier eine theoretische Frage stellen. Ich muss für einen Professor an meiner Uni eine wissenschaftliche Ausarbeitung über ein Softwareprojekt, welches ich zur Zeit programmiere, erstellen. Aktuell sitze ich an der Dokumentation der Implementierung und hier stockt es.
Mir stellt sich die Frage wie man diese Phase am besten dokumentiert. Den kompletten Programmcode kommentarlos Dahin “zu klatschen” bringt ja nichts. Hab aber gerade auch keine Idee wie ich die Implementierung am besten in worte Fasse. Hat hier jemand (ungeachtet des konkreten Themas) anregungen oder vll Beispiele? Eine suche bei google brachte mir leider keine brauchbaren Beispiele.
Die Dukumentation sonn nicht den Code erklären, sondern nachvollziehbar machen, welche Struktur Deinem Programm zu Grunde liegt und, warum Du Dich für bestimmte Konstrukte und Entwurfsmuster entschieden hast. Die Dokumentation ist also immer hochgradig mit deinem Programm verknüpft,m so dass Du wahrscheinlich keine Copy/Paste-Forlagen finden wirst.
Aber eine guter Anhalt für den Aufbau einer Doku findes Du hier: http://www.arc42.de/.
Vor der Implementierung sollte man schon ein paar Diagramme der UML-Familie erstellt haben. Ganz vorn sind da Use-Case-Diagramme dabei. Interaktionsdiagramme sind auch in der Designphase sinnvoll. Ein Klassendiagramm würde ich aber erst am Ende von einem Generator aus dem fertigen Code erzeugen lassen.
Die Analyse und Entwurfsphase ist klar . Hab mit einem Use-Case klar gemacht was das Programme können soll / muss. Schrifftlich hab ich weitere nicht-funktionale Anforderungen gestellt dann weitere Mit Einem Packetdiagramm hab ich die grobe Strucktur und vor allem die Abhängigkeiten und Eingliederung im bereits bestehenden System dargestellt. Zum Abschluss des Entwurfs hab ich einen Objektorientierter Entwurf in Form eines Klassendiagramms (wurde aus dem Code generiert ) erstellt.
Nun kommt bei mir der Punkt Implementierung. Die frage ist da nun soll ich auf das eigentliche Programmieren eingenen also in welcher Reihenfolge wurde was erstellt und worauf ich achten musste (z.B Abhängigkeiten / Probleme)?
Also ich denke am sinnvollsten ist es, nicht den Quellcode zu erklären, sondern den Weg dahin.
Es muss also erklärt werden, warum du dich für bestimmte Dinge entschieden hast, welche Probleme auftraten und wie du diese gelöst hast und warum du sie so gelöst hast. Dabei wichtige oder besonders komplizierte Codestellen nochmal kurz erläutern und gut ist.
In diesem Fall ist der Weg das interessante. Nicht das Ziel.
Ansonsten ist es in solchen Fällen immer hilfreich einen Kommilitonen (oder deinen Tutor, falls vorhanden) zu fragen, der das schon hinter sich hat. Ggf. kann er dir auch eine eigene Arbeit als Beispiel geben, an der du dich orientieren kannst. Sollte so jemand nicht greifbar sein, frag deinen Prof. Er sollte dir das definitiv beantworten können und in der Regel ist es auch keine Schande so etwas zu erfragen (sofern er es dir noch schon mal gesagt hat^^) Eine bindende und definitiv korrekte Antwort wirst du jedenfalls nur von ihm kriegen können.
Wichtigste Regel:
Interfaces und Klassen im Header dokumentieren. Warum gibt es die jeweilige Klasse / das jeweilige Interface?
Die Methoden erzählen, was diese Klasse tut und wenn es sauber ist, dann benötigt man dort nicht viel Dokumentation. Komplexe Stellen dann zusätzlich mit Dokumentation versehen.
@Sym : Es geht um eine wissenschaftliche Arbeit in Form einer Projektdokumentation. Danke für eure Hilfen ich denke damit kann ich was Anfangen und eine grobe Richtung einschlagen
Zur Implementierungsphase gehören auch Unit Tests. Diese zählen auch als Dokumentation. Unit Tests wiederum kann man durch Class-Tree-Method Diagramme (oder so ähnlich) einigermaßen herleiten und dokumentieren/verwalten. Unit Tests nochmal ausführlicher zu dokumentieren ist zwar eher was für Streber, aber für wissenschaftliche Arbeiten eigentlich auch nicht so ungewöhnlich.
) erstellt.