Erklärung zu Quellcode, wie detalliert???

[LucyLoreley]

Hallo

Wie genau muss ich in meiner Dokumentation den Quellcode beschreiben!!

Ich hab ne Methode die ruft 2 Datenbanken auf, liest diese und ruft dann mehrer Methoden auf die zb. Die Datenbank vergleichen usw.

Wie genau muss ich das erklären??? muss ich den Aufruf der Datenbanken erklären? Soll ich dann gleich noch Quellcode mit rein hängen??? Oder den kompletten Quellcode als Anhang und einen Verweis drauf???

Muss ich z.B. sagen: hier wurde ein for-schleife benutzt um die Daten der Datenbank auszulesen....?? :confused:

Bitte, kann mir jemand helfen???

Vielen Dank!!!

[Sariel]

Muss ich z.B. sagen: hier wurde ein for-schleife benutzt um die Daten der Datenbank auszulesen....?? :confused:

Ja, und eine entsprechende Erklärung zu For-Schleifen, gehört dann in den Anhang.

[LucyLoreley]

:beagolisc Echt jetzt??? Ohne Scherz???

Also muss ich alles, im Anhang, erklären??? Soll ich dann auch .Net und C# näher erklären???

[Fabi]

Würd ich echt nicht machen, dass du jede Codezeil kommentierst.

Ich würde überhaupt Code nur in die Doku reinbringen, wenns ein besonders komplizierter Codeteil ist.

Zuviel Code verwirrt nur.

[Sariel]

:beagolisc Echt jetzt??? Ohne Scherz???

Mir wurde zu meiner Doku Zeit nahe gelegt - die Doku soll auch von Lesern verstanden werden, die von dem Thema nicht viel Ahnung haben.

[LucyLoreley]

Also den kompletten Code wollte ich in den Anhang stellen. Und dann gibt es eben eine Methode wo sozusagen das wichtigste passiert. Diese Methode will ich näher erklären. Den Aufruf der Datenbank, da der über C# ist, usw.

[Sariel]

Ja, dann ist doch Okay.

Ohne Dein Projekt jetzt genauer zu kennen, - aber sowas hat man dann ja im Gefühl, welches Wissen der/ein Leser haben muss, um es zu verstehen.

[LucyLoreley]

Hm ich weis auch nicht so recht. Ich neige dazu etwas total breit zu treten das sich der Text dan unheimlich langweilig liest.

Ich will aber das dieses Projekt gut wird!!!

Aber muss ich jetzt sowas wie for-Schleifen, Klassen oder Instanzen erklären??

[Sariel]

Aber muss ich jetzt sowas wie for-Schleifen, Klassen oder Instanzen erklären??

Ja. Meiner Meinung nach schon - weil eine gute Doku ist auch eine verständliche.

Und wenn die Erklärungen im Anhang (ähnl. Glossar) stehen, ist doch keiner gezwungen es zu lesen. Oder?

[LucyLoreley]

ok danke!!!

Dann werd ich deinen Ratschlag befolgen!!!

Ich hoffe ich werde irgendwann damit fertig und auch hoffe ich das sie gut wird!!!

Danke nochmal für die Hilfe!!!

[zirri]

Hallo

Ich hab ne Methode die ruft 2 Datenbanken auf, liest diese und ruft dann mehrer Methoden auf die zb. Die Datenbank vergleichen usw.

Ich wuerde ungefaehr so kommentieren:

- // hier rufe ich 2 Datenbanken auf

[LucyLoreley]

Meinst du im Anhang beim Quellcode oder direkt in der Doku??

[wo0zy]

wo hier schon von quellcode-erklärung gesprochen wird...wie siehts eigentlich mit struktogrammen aus, muss ich für alles ein struktogramm machen oder nur für das was ich als wichtig empfinde?

[Quenten]

Soweit ich weiß ist ein Struktogramm keine Vorraussetzung, aber es würde sich natürlich gut machen in deiner Doku. Wenn dein Programm komplex ist, würde ich es splitten und einzelne Struktogramme entwerfen, wenn nicht, würde eins reichen.

[Jaraz]

Aber muss ich jetzt sowas wie for-Schleifen, Klassen oder Instanzen erklären??

Ja. Meiner Meinung nach schon - weil eine gute Doku ist auch eine verständliche.

Und wenn die Erklärungen im Anhang (ähnl. Glossar) stehen, ist doch keiner gezwungen es zu lesen. Oder?

Sorry aber das ist imho nicht richtig.

Die erstellst eine betriebliche Projektarbeit und nutzt die Techniken die du in der Ausbildung gelernt hast.

Niemand muss erklären was eine Klasse, eine Schleife, eine SQL Abfrage oder ähnliches ist. Nur das was du damit machst, musst du irgendwo erklären.

Quellcode kommentiert man da wo es Sinn macht, also da wo ein Aussenstehender ohne Hinweis nicht mehr weiß was passiert.

Auch was absolut logisch ist oder sich aus den gewählten Bezeichnern ergibt, muss nicht kommentiert werden.

private String counter=0; // interne Zählervariable <= Kommantar hier überflüssig

Gruß Jaraz

[AlexF]

Also da ich sowas ähnliches vor ein paar tagen weggeschickt habe kann ich dir folgendes Raten. Im anhang hängst du den queltext an. verweis darauf und erklär in der doku kurz was dein QT macht. Beschriebe die DB und wie du zu der gekommen bist ERM Normalisierung und dann verfasst du keine Kundendoku sondern eine entwicklerdoku in der du dann den quelltext ganz genau erklärst und hängst sie der projektdoku an!

[matthias_nordwig]

Um die Logik mal umzudrehen: Du beschreibst in erster Linie mit Worten was du tust, und untermauerst das eventuell ganz dezent mit einigen Auszügen aus dem Quellcode. Kommentieren im Quellcode ist wie Quellcode selbst.. liest sich eh kein Schwein durch .. oder würdest du dass, wenn du Prüfer währst und bereits die 20. Arbeit mit 80-seitigem Quellcode durchliest, obwohl du das eher als Nebentätigkeit betreibst und su statt dessen mit deiner Frau/Freundin ...