Kommentare in Java

[Wang]

Hallo Java-Freunde! :toll:

Ich muss folgende Aufgabe lösen:

(a) Die Klasse Euklid implementiert den euklidischen Algorithmus. Erweitern Sie diese Klasse sehr ausführlich um geeignete Kommentare. Die Kommentare sollten folgendes beinhalten:

(i) Ein Dokumentationskommentar, der die gesamte Klasse beschreibt und Sie als Autor nennt.
(ii) Ein Dokumentationskommentar, der das Programm mit dem aktuellen Datum versioniert.
(iii) Ein Dokumentationskommentar, der die Main-Methode beschreibt. Den Parameter args können sie wie im Beispiel aus dem Skript dokumentieren.
(iv) Ein- oder mehrzeilige Kommentare an Stellen, an denen Sie es für sinnvoll halten.

Bemerkung:
Um “schöne” javadoc-Kommentare zu schreiben, in denen zum Beispiel Formeln in mathematischer Notation angezeigt werden, ist es nötig, sich mit html auszukennen. Wir empfehlen deshalb zur Einarbeitung:
SELFHTML 8.1.2 (HTML-Dateien selbst erstellen).

Meine (Teil)Lösung:

/**
* <font color="green"><big>Euklid Klasse zum Bestimmen des groessten gemeinsamen Teilers ggT
* zweier natuerlicher Zahlen a und b mittels des Euklidschen Algorithmus</big></font>
*
* @author <b>Max Mustermann</b>
* @version <b>1.0 (29.10.2009)</b>
*/

public class Euklid
{
  /**
  * @param args Array mit Parametern - wird von dieser Methode nicht verwendet.
  */
  public static void main(String[] args)
  {
    // Variablen
    int a = 49;       // Zuweisung von definierten Anfangs-
    int b = 14;       // und Startwerten (Initialisierung)

    // Kontrollstruktur
    while(b!=0)
    {
       if(a>b)
       {
          a = a-b;
       }
       else
       {
          b = b-a;
       }
    }
    int ggt = a;
    System.out.print("Der GGT von 49 und 14 ist: " + ggt); // der Wert des größten gemeinsamen
                                                           // Teilers wird auf dem Bildschirm
                                                           // ausgegeben
  }
}

Bei Teilaufgabe (iii) weiß ich nicht ganz, wie ich die main-Methode beschreiben soll. ???:L
Wäre sehr nett, wenn jemand seine Meinung dazu schreibt und wirklich jeden noch so kleinen Fehler anprangert.
Vielen Dank.

 

[hdi]

edit: Hab nicht gesehen dass du auch einen Klassenkommentar hast, das passt also.

Die main()-Methode, naja soviel gibt es dazu nicht zu sagen. Schreib einfach noch irgendeinen Satz über das @param Tag, zB "Dies ist die Methode in der das Programm startet" oder sowas.

Ansonsten hab ich noch was zu bemängeln:
"Variablen" und "Konstrollstruktur" sind kein sinnvoller Kommentar, ich meine das sieht man ja sofort, auch ohne Kommentar. Dein Kommentar sollte also lieber beschreiben, für was diese Variablen da sind und was die Kontrollstruktur denn überprüft/auswertet.
So wie du es zB im letzten Kommentar getan hast, der ist ja auch gut.

PS: Du könntest dir überlegen statt einzeilige Kommentare lieber mehrzeilige zu machen:

/*Der Wert des größten gemeinsamen Teilers wird auf dem Bildschirm ausgegeben */
System.out.print("Der GGT von 49 und 14 ist: " + ggt);

Wenn der Kommentar dann zu lang wird, wird er sauberer umgebrochen als bei einzeligen Kommentaren.

 

[L-ectron-X]

Bei Teilaufgabe (iii) weiß ich nicht ganz, wie ich die main-Methode beschreiben soll. ???:L

/**
 * Programmeinstiegspunkt - startet die Ausführung der Anwendung.
 * @param args Ein Feld mit Argumenten, welche dem Programm beim Aufruf mit übergeben werden können. 
 */

 

[bygones]

find ehrlich gesagt schade dass die Aufgabe so ins detail geht... das verleitet eher zu den berüchtigten "noise" Kommentaren...

je mehr kommentar ein code braucht umso unverstaendlicher ist er und das sollte nach verbesserung schreien - nicht noch ne zeile kommentar

 

[L-ectron-X]

Das mag schon sein, es geht hier aber sicher darum, die möglichen Kommentare zu kennen, zu unterscheiden und richtig einzusetzen.

 

[Wang]

Danke für eure Hilfe, ich habe alle Vorschläge umgesetzt. :toll:

Zwei Fragen:

1. Bin ich der Teilaufgabe (ii) mit meiner Datumsangabe gerecht geworden oder kann man das programmiertechnisch noch feiner schreiben?
2. Ich habe das Wort "Variablen" entfernt. Die Frage ist nur, durch was soll ich "Kontrollstruktur" ersetzen bzw. soll ich jede einzelne Befehlszeile beschreiben, um der Aufgabenstellung gerecht zu werden. ???:L

Hier die aktualisierte Quelldatei:

/**
* <font color="green"><big>Euklid Klasse zum Bestimmen des groessten gemeinsamen Teilers ggT
* zweier natuerlicher Zahlen a und b mittels des Euklidschen Algorithmus</big></font>
*
* @author <b>Max Mustermann</b>
* @version <b>1.0 (29.10.2009)</b>
*/

public class Euklid
{
  /**
  * Programmeinstiegspunkt - startet die Ausführung der Anwendung.
  * @param args Ein Feld mit Argumenten, welche dem Programm beim Aufruf mit übergeben werden können.
  */
  public static void main(String[] args)
  {
    /* Zuweisung von definierten Anfangs- und Startwerten */
    int a = 49;
    int b = 14;

    // Kontrollstruktur
    while(b!=0)
    {
       if(a>b)
       {
          a = a-b;
       }
       else
       {
          b = b-a;
       }
    }
    int ggt = a;
    /* Der Wert des größten gemeinsamen Teilers wird auf dem Bildschirm ausgegeben */
    System.out.print("Der GGT von 49 und 14 ist: " + ggt);
  }
}

Danke.

 

[Marco13]

PS: Du könntest dir überlegen statt einzeilige Kommentare lieber mehrzeilige zu machen:

/*Der Wert des größten gemeinsamen Teilers wird auf dem Bildschirm ausgegeben */
System.out.print("Der GGT von 49 und 14 ist: " + ggt);

Das find' ich jetzt nicht so gut. Ich schreibe grunsätzlich innerhalb von Methoden NUR einzeilige Kommentare, die (bis auf seltenSTe Ausnahmen) Am Anfang der Zeile anfangen. Wenn man mal einen Block auskommentieren will, indem 20 "mini-Kommentare" mit /*...*/ sind, ist das ziemlich lästig (ja, markieren, Strg+7 ... Kennt hier noch jemand TextPad?)

@Wang: Ja, "Kontrollstruktur" sagt wirklich nicht viel aus, aber was soll man schon dazu sagen - man KÖNNTE noch die Grundidee hinter dem Euklid skizzieren, so wie

// Wenn eine Zahl zwei Zahlen teilt, dann auch
// ihre Differenz. Wende dieses Prinzip so lange
// an, bis der ggt gefunden ist (bla, bla...)
while (...)

oder so ähnlich...

 

[Wang]

Danke, Marco 13.

Ich habe deine Vorschläge umgesetzt.

Nochmals kurz meine Frage:
Passt das mit der Datumsangabe so, oder gibt es eine Möglichkeit, das noch "feiner" auszudrücken bzw. wie würde das ein professioneller Programmierer machen?

Thanks.

 

[Landei]

Setze mal a = 0, b = 14 und warte auf's Ergebnis. Oder a =-1, b = 53...

 

[Wang]

Setze mal a = 0, b = 14 und warte auf's Ergebnis. Oder a =-1, b = 53...

Nicht mit mir!
Also nochmals wegen dem Datum... Gibt es eine Möglichkeit, dies feiner darzustellen, als ich das gemacht habe?

 

[Marco13]

Was meinst du denn mit "feiner"? ???:L :bahnhof: Man könnte jetzt drüber philosophieren ob man ein Englisches Datumsformat nimmt, oder Bindestriche statt Punkte, aber was heißt "feiner"?

 

[Wang]

Was meinst du denn mit "feiner"? ???:L :bahnhof: Man könnte jetzt drüber philosophieren ob man ein Englisches Datumsformat nimmt, oder Bindestriche statt Punkte, aber was heißt "feiner"?

Typische Gedanken eines Anfängers...

 

[Beni]

Übrigens: um fette oder farbige Schrift kümmert sich das Tool, welches den Kommentar dann z.B. in eine html-Seite verwandelt, all deine <b>s und etc sind überflüssig.

 

[Wang]

Übrigens: um fette oder farbige Schrift kümmert sich das Tool, welches den Kommentar dann z.B. in eine html-Seite verwandelt, all deine <b>s und etc sind überflüssig.

Wie genau meinst du das...?

Ich arbeite nur mit der Kommandozeile und benutze keine Tools.

 

[maki]

Ich arbeite nur mit der Kommandozeile und benutze keine Tools.

Glaub ich nicht, ausser du programmierst so:

C:\>copy con Test.java

Mal ernsthaft, du brauchst nicht allzuviele HTML Tags verwenden, das JavaDoc Doclet kümmert sich darum dass die wichtigen Dinge Fett hervorgehoben werdne.

 

[0x7F800000]

Ich arbeite nur mit der Kommandozeile und benutze keine Tools.

Und die javadoc-Kommentare schreibst du um sie später auszudrucken und damit die Wände zu tapezieren????:L

 

[Wang]

Glaub ich nicht, ausser du programmierst so:

C:\>copy con Test.java

Mal ernsthaft, du brauchst nicht allzuviele HTML Tags verwenden, das JavaDoc Doclet kümmert sich darum dass die wichtigen Dinge Fett hervorgehoben werdne.

Ich habe das JDK 6 installiert und arbeite nur mit dem Editor und der Kommandozeile. Das habe ich auch nur deshalb eingebaut, um etwas "herumzuspielen" - wohl typisch für einen Anfänger.
Gibt es noch andere Möglichkeiten, Einfluss auf die Schriftgröße, etc. zu nehmen?

 

[maki]

Ich habe das JDK 6 installiert und arbeite nur mit dem Editor und der Kommandozeile. Das habe ich auch nur deshalb eingebaut, um etwas "herumzuspielen" - wohl typisch für einen Anfänger.

Fijnd ich gut was du da machst, die meisten Anfänger holen sich eine Super-Komplexe Proff. IDE die sie überfordert oder eine die nur an Schulen verwendet wird, finde dein Vorgehen am besten, leider machen das nicht alle so

Gibt es noch andere Möglichkeiten, Einfluss auf die Schriftgröße zu nehmen?

Ja, gibt es, solltest du aber imho lassen, JavaDocs sind mittlerweile so etwas wie ein Standard, jeder Javaentwickler liest zumindest die von Sun, deine sollten genauso aussehen, macht es einfacher für alle.

 

[Wang]

Fijnd ich gut was du da machst, die meisten Anfänger holen sich eine Super-Komplexe Proff. IDE die sie überfordert oder eine die nur an Schulen verwendet wird, finde dein Vorgehen am besten, leider machen das nicht alle so

Mir ist das Erlernen der Grundlagen echt am wichtigsten, der Rest (Entwicklungsumgebungen) kann später kommen.

Ja, gibt es, solltest du aber imho lassen, JavaDocs sind mittlerweile so etwas wie ein Standard, jeder Javaentwickler liest zumindest die von Sun, deine sollten genauso aussehen, macht es einfacher für alle.

Ausschlaggebend für die "HTML-Spielerei" war auch dieser Satz aus der Angabe:

Bemerkung:
Um “schöne” javadoc-Kommentare zu schreiben, in denen zum Beispiel Formeln in mathematischer Notation angezeigt werden, ist es nötig, sich mit html auszukennen. Wir empfehlen deshalb zur Einarbeitung:
SELFHTML 8.1.2 (HTML-Dateien selbst erstellen).

Danke für eure Hilfe soweit.

 

[Wang]

Kurz zu dem Rest der Aufgabe:

(b) Erzeugen Sie die Dokumentation in einem Unterverzeichnis \doku:
javadoc -d .\doku Euklid.java

(c) Falls alles geklappt hat, erzeugen Sie eine weitere JAR-Datei, in der die dokumentierte Klasse Euklid und die erstellte Dokumentation zusammengefasst sind:
jar cvf euklid.jar Euklid.* .\doku

(b) ist klar, aber die Formulierung "eine weitere JAR-Datei" verunsichert mich, denn ich musste doch bisher in dieser Aufgabe keine JAR-Datei erstellen ???:L

Was genau ist mit der "dokumentierten Klasse Euklid" gemeint; ist das einfach die über javac erzeugte Datei?

Heißt das, dass ich die Datei Euklid.java gar nicht in die JAR-Datei packen soll?

Danke

 

[Leroy42]

(b) ist klar, aber die Formulierung "eine weitere JAR-Datei" verunsichert mich, denn ich musste doch bisher in dieser Aufgabe keine JAR-Datei erstellen ???:L

Tja dann erstell eben einfach eine .jar-Datei

Was genau ist mit der "dokumentierten Klasse Euklid" gemeint; ist das einfach die über javac erzeugte Datei?

Wahrscheinlich ja.

Heißt das, dass ich die Datei Euklid.java gar nicht in die JAR-Datei packen soll?

Richtig die .java-Dateien gehören nicht in eine .jar-Datei hinein. Nur die .class-Dateien sind notwendig.

 

[Wang]

Danke Leroy42.

Ist es normal, dass die Dateien beim Packen in eine JAR-Datei komprimiert werden?

Wie kann ich nachsehen, was in einer JAR-Datei enthalten ist (um zu überprüfen, ob die gewünschten Dateien auch enthalten sind)?

 

[Leroy42]

Ist es normal, dass die Dateien beim Packen in eine JAR-Datei komprimiert werden?

Ja!

Wie kann ich nachsehen, was in einer JAR-Datei enthalten ist (um zu überprüfen, ob die gewünschten Dateien auch enthalten sind)?

Jede .jar-Datei ist gleichzeitig eine stinknormale zip-Datei. Einfach mit einem tool wie
winzip oder 7-Zip ansehen.

 

[Wang]

Danke, ich habe heute wieder sehr viel dazugelernt. :toll:

Eine letzte Frage habe ich aber noch:
ist es normal, dass in der JAR-Datei der Unterordner doku verschwunden ist?

 

[Leroy42]

ist es normal, dass in der JAR-Datei der Unterordner doku verschwunden ist?

Keine Ahnung wie du die .jar-Datei erstellt hast. Wenn der Unterordner doc beim erstellen
nicht angegeben wurde wird er eben nicht mit aufgenommen.

Wenn du allerdings kein package doc hast oder in diesem Unterordner
keine Resourcen sind brauch die .jar-Datei ihn auch nicht.

 

[Wang]

Ich habe das über diesen Befehl gemacht:

jar cvf Eukild.jar Euklid.* -C doku .

Im Ordner Euklid befindet sich die Klasse Euklid und im Unterordner ist die Dokumentation.

 

[Nicer]

Commis benutze ich eig nur dassich etwas :

1) Wichtiges nicht vergesse
2) etwas was noch bugs hat makiert
3) wennich es anderen erklären will

Zu deiner Aufgabe :

Zur not beschreibst du den Ablauf der Main() , das sollte passen

MfG Nicer