Dokumentation von Software

[pippo]

Ich hab zwar im Offtopic schon in meinem Doku-Thread gefragt, aber hier ist es wohl besser aufgehoben.

Ich hab 800 Zeilen C-Code für meinen uC geschrieben und muss das nun in meine Projektdoku (Word) einfügen. Nun bin ich mir unsicher, wie man sowas machen soll. Ich kann ja kaum Zeile für Zeile erklären, drum hätt ich mal das wichtigeste rausgesucht, erklärt und im Anhang den kompletten Code auskommentiert angefügt. Macht man das so, oder anders?

Das ganze gehört zur Abschlussprüfung des Technikers. Unsere Lehrer braucht man da net fragen, denn wenn ich mir anschau auf was die ne 1 geben, wirds mir schlecht. Die Doku hätt später gern den Bewerbungen beigelegt, deshalb der Aufwand.

[RMC]

Macht man das so, oder anders?

Im Prinzip hat Code in der Dokumentation nichts zu suchen, auch die wichtigsten Abschnitte sind dort eher Fehl am Platz. Auch ist es unüblich, den ausgedruckten Code im Anhang beizufügen.

Die Dokumentation erklärt nicht den Code, sondern das Projekt selbst sowie dessen Struktur und Ablauf (Analyse, Pflichtenheft, etc.).

Für Code ansich gibt es eigene Dokumentationssysteme (zB Javadoc, Doxygen etc.). Meistens erzeugen diese Systeme eine HTML Ausgabe, die man normalerweise dem RC beifügt oder zum Download zur Verfügung stellt. Aber bitte nicht ausdrucken ;)

[Monger]

Wenn, dann wird das Zeug ohne große Erklärung in den Anhang gehängt. Wie RMC schon erklärt hat: Code hat eigentlich in der Projektdokumentation nix zu suchen, das geht eigentlich zu weit ins Detail. Nix auskommentieren, wozu? Im Idealfall erhältst du sogar das Syntax Highlighting.

Was das kommentieren angeht... normalerweise erfüllt dein Code ja eine bestimmte Aufgabe. Den solltest du dokumentieren, sinnvollerweise direkt am Anfang. Und diese Aufgabe gliedert sich üblicherweise in kleinere Abschnitte, die sich sinnvollerweise dann in einzelnen Methoden manifestieren. Auch diese dokumentierst du direkt über der Deklaration.

Wenn es dir schwer fällt, kurz und knapp zu erklären was bestimmte Abschnitte in deinem Code tun, sollte dir das zu denken geben! ;)
Vielleicht ist dann der Code selbst schlicht noch nicht strukturiert genug.

Es gibt auch Standards dafür, wie Code-Dokumentation aussehen soll. Wie die allerdings in C aussieht, weiß ich nicht.

[maximAL]

Im Prinzip hat Code in der Dokumentation nichts zu suchen, auch die wichtigsten Abschnitte sind dort eher Fehl am Platz. Auch ist es unüblich, den ausgedruckten Code im Anhang beizufügen.

Die Dokumentation erklärt nicht den Code, sondern das Projekt selbst sowie dessen Struktur und Ablauf (Analyse, Pflichtenheft, etc.).

Für Code ansich gibt es eigene Dokumentationssysteme (zB Javadoc, Doxygen etc.). Meistens erzeugen diese Systeme eine HTML Ausgabe, die man normalerweise dem RC beifügt oder zum Download zur Verfügung stellt. Aber bitte nicht ausdrucken ;)
Du weißt das, ich weiß das, die meisten Entwickler auch. Aber meine Software Engineering Professorin wusste es nicht. Von Sachen wie Doxygen hielt sie überhaupt nichts - automatisch generiert ist ja keine richtige Doku und bringt ja keinem was. Ausgedruckt werden musste es dann trotzdem.
Hauptsache, man hat jede Funktion mit viel Gerede in der Doku breitgetreten...

[pippo]

Ok, danke. Dann kann ich also die Hardwaredoku von gestern auch wieder rausschmeissen :)

Den Code wolln die Lehrer unbedingt sehen, dann leg ich den einfach als Anhang bei

[Gast]

Ok, danke. Dann kann ich also die Hardwaredoku von gestern auch wieder rausschmeissen :)

Den Code wolln die Lehrer unbedingt sehen, dann leg ich den einfach als Anhang bei

Was sind das für Lehrer bzw. was für eine Schulform? Ggf. würde ich dann doch eher machen, was die Lehrer wollen. Denn es bringt dir ja auch nichts, wenn du dann eine schlechte Schulnote bekommst.


Den Code wolln die Lehrer unbedingt sehen, dann leg ich den einfach als Anhang bei

Ich hatte bei meinem Abschlussprojekt (IHK) eigentlich eine extrem umfangreiche Doku gehabt, in der ich aber nicht den Code reingepastet u. beschrieben hatte, sondern eben Projektaufbau, Projektablauf, Struktur, Komponenten usw. (nach MSF Modell)
Zusätzlich hatte ich aber den Code als Projekt (auf CD) beigefügt, der darüberhinaus noch extrem durchkommentiert war.

Ergebnis war, dass ich darauf eine 3- bekam. Ein Prüfer hat sich den Code angeschaut, die anderen konnten es angeblich nicht öffnen. Auf deutsch, die haben den sich gar nicht erst angeschaut. Somit hat dann einfach bei deren Bewertung der Code gefehlt, obwohl er ja eigentlich vorhanden war.

Ich würde mir es eher drei mal überlegen, ob du hier bei gewissen Institutionen Experimente machen willst.