JavaDoc-Dokumentierung und Praesentation in Vorlesung

LondonBeats
Neuling
Neuling
Beiträge: 2
Registriert: 19. Jun 2012 15:43

JavaDoc-Dokumentierung und Praesentation in Vorlesung

Beitrag von LondonBeats »

Hallo.

1. Im letzten Programmierprojekt (AI1) wurde ausdruecklich vor zu ausfuehrlicher Kommentierung des Projekts gewarnt. Hinsichtlich der JavaDoc-Kommentare wird in diesem Projekt, in der Aufgabenstellung das Gegenteil verlangt. Nun sehe ich, dass eine starke JavaDoc-Kommentierung durchaus die Uebersicht und Laenge des Codes nachteilig beeinflussen kann. Stoeren lassen sollte ich mich trotzdem nicht dran?

2. In der letzten AI2-Vorlesung praesentierte Prof. Fuernkranz eine Musterloesung zum Programmierprojekt. In dieser wurde der Spielverlauf aktiv mitgeloggt. Innerhalb des Programmierprojekt gab es zu dieser Funktion keine Aufgabenstellung die diese Funktion verlangt. Auch fehlt eine jegliche Vorimplementierung dieser Funktion. Kann ich daher davon ausgehen, dass das Fehlen / Vorhandensein dieser Funktion in der Abgabe keinen Einfluss auf die Bepunktung haben wird?

Gruesse,
LondonBeats.

Benutzeravatar
mmec
Sonntagsinformatiker
Sonntagsinformatiker
Beiträge: 203
Registriert: 7. Sep 2011 17:59
Wohnort: Darmstadt

Re: JavaDoc-Dokumentierung und Praesentation in Vorlesung

Beitrag von mmec »

Hallo LondonBeats,

1. Die JavaDoc Kommentierung passiert ja über der Methode, also finde ich gar nicht dass das so unübersichtlich ist. Dort solltest du einfach beschreiben was die Methode macht und außerdem sollen ggf. Rückgabewerte und ggf. Parameter beschrieben werden. Jemand der das Programm nicht kennt sollte verstehen was die Methode macht. Die ganzen Details, wie genau die Sachen innerhalb der Methode passieren sind nicht wichtig. In der Java API sind die Sachen ja auch so beschrieben. Du kannst ja mal schauen wie es da so aussieht: Link zur Klasse String in der Java API. Du sollst die Kommentare halt nicht unnötig lang machen.

Innerhalb der Methode beschreibst du Codeteile bei denen nicht sofort ersichtlich ist was oder warum etwas passiert. Ein weiteres Beispiel für eine Kommentierung ist z.B. die vorgegebene Klasse MauMau im Programmierprojekt.

2. Wenn es nicht in der Aufgabenstellung steht soll es wohl auch nicht passieren. Wenn du in der Klasse MauMau mal nach "System.out.print" suchst, werden dir alle Code Teile markiert in der du Ausgaben in der Konsole bekommst. Du siehst dort dass dir nur am Anfang und am Ende des Spiels etwas über die Konsole ausgegeben wird. Ich habe die Vorlesung nicht gesehen, aber ich nehme mal an dass das eine andere Version war.

Grüße, Johannes
Zuletzt geändert von mmec am 19. Jun 2012 22:15, insgesamt 1-mal geändert.
Grund: verwirrender Schreibfehler
FC SEEMOO No.1

Benutzeravatar
Owyn
BSc Spammer
BSc Spammer
Beiträge: 1012
Registriert: 5. Sep 2005 21:53
Wohnort: Rheingau

Re: JavaDoc-Dokumentierung und Praesentation in Vorlesung

Beitrag von Owyn »

Hallo,

richtig: in der Aufgabenstellung ist davon die Rede, dass jede Methode "ausführlich" kommentiert werden soll.
In Romane muss das natürlich nicht ausarten - bei einer einfachen Getter-Methode reicht eine Zeile, bei vielen anderen Methoden müssen es auch nicht wesentlich mehr sein (zuzüglich @param- und @return-Zeilen).

In den Javadoc-Kommentaren müssen Sie nicht auf die interne Funktionsweise der Methoden eingehen, dafür sind die "normalen" Kommentare gedacht (die nur bei komplexen Stellen nötig sind).

Bei einer Methode "boolean schalten(int gang)" einer Klasse "Auto" reicht also z.B. der Kommentar "Wechselt den aktuellen Gang, sofern die Kupplung getreten ist. @param gang Der neue Gang. @return true, wenn der Gang gewechselt wurde, false, wenn die Kupplung nicht getreten ist." Es muss nicht darauf eingegangen werden, wie das Getriebe genau funktioniert.

In einer komplexeren IDE lassen sich die Kommentarblöcke "einfalten", so dass sie den Blick auf den Code weniger stören. Das ist in Blue nicht möglich, bei einem vergleichsweise kleinen Projekt wie dem ProPro sollte es aber trotzdem möglich sein, den Überblick zu behalten.


Zu 2.:
In der Aufgabenstellung sind solche Kontrollausgaben nicht gefordert, also müssen Sie auch keine schreiben. Sie können natürlich, wenn das Ihnen bei der Programmierung hilft.

Gruß,
Christian Heinig
All those who believe in psycho-kinesis, raise my hand.
(Steven Wright)

habemuskeln();
Neuling
Neuling
Beiträge: 2
Registriert: 19. Jun 2012 13:22

Re: JavaDoc-Dokumentierung und Praesentation in Vorlesung

Beitrag von habemuskeln(); »

mmec hat geschrieben:2. Wenn es nicht in der Aufgabenstellung nicht steht soll es wohl auch nicht passieren
Hebt dein zweites "nicht" das erste auf? Es war doch kein fieser Versuch der Irreführung :cry:

Benutzeravatar
mmec
Sonntagsinformatiker
Sonntagsinformatiker
Beiträge: 203
Registriert: 7. Sep 2011 17:59
Wohnort: Darmstadt

Re: JavaDoc-Dokumentierung und Praesentation in Vorlesung

Beitrag von mmec »

Hallo habemuskeln(),

war nur ein Schreibfehler meinerseits. Werd es korrigieren. :mrgreen:

Grüße, Johannes
FC SEEMOO No.1

Antworten

Zurück zu „Archiv“