[Gottzilla]

Welche Grundlagen sollten beachtet werden, damit der Code schön lesbar ist? Eindeutige Variablennamen zu benutzen und nach einem ; eine neue Zeile Anfangen und nach { } ebenfalls und zusätzlich den Code einrücken dürfte eigentlich jedem klar sein. Aber was gehört sonst noch dazu?

[edit] hab net so genau gewusst, wo ich das reinposten soll. Wenn ihr meint das wäre woanders besser aufgehoben, dann verschiebts einfach

[pago]

Versuch bei einer Formatierungsweise zu bleiben.
Die meisten Sachen sind Geschmackssache. Ich bevorzuge eine leicht modifizierte Formatierung gemäß den Java Richtlinien (ja, da gibts sogar was von Sun, dass beschreibt, wie man seinen Code formatieren sollte).

Aber am wichtigsten ist wirklich, dass du einheitlich formatierst. Es gibt nichts schlimmeres, als wenn du einmal so und einmal so einrückst.

[ehli75]

Also für mich gehört auf jeden Fall da noch die Doku rein ... d.h. für jede Methode javadoc-Kommentare schreiben ... und wenn nötig auch für die Attribute ... dann mache ich auch noch in den Methoden normale Kommentare, damit ich nach einem Jahr auch noch weiss, was ich da gemacht habe (oftmals weiss ich das eine Woche später schon nicht mehr . )
Bei den schließenden geschweiften Klammern habe ich mir angewöhnt einen kurzen Kommentar dahinter zu setzen, was für eine Klammer da zu geht, denn bei mehrfach geschachtelten Schleifen und langen Methoden (wo ich die öffnende Klammer nicht mehr im Sichtfeld habe) wird das sonst ganz schnell unübersichtlich.

Michael

[pago]

Zum Thema JavaDoc: Nicht jede Methode braucht einen Kommentar. Der Methodenname sollte klar genug sein. Hier mal ein Beispiel:

public void saveSettingsToFile(File f) throws IOException {
	FileOutputStream fos = new FileOutputStream(f);
	fos.write(this.getSettingsAsString());
	fos.close();
}

Diese Methode hat keinen Kommentar. Warum sollte ich die Menge an Code, die ich überblicken muss, erhöhen, und daraus z.B. das hier zu machen:

/**
 * <p>This method saves the settings of this object to the specified file.</p>
 *
 * @return void
 * @param f The file which shall contain the settings
 * @throws An IOException that might happen while writing the settings.
 */
public void saveSettingsToFile(File f) throws IOException {
	// Create the OutputStream
	OutputStream fos = new FileOutputStream(f);
	// Write settings
	fos.write(this.getSettingsAsString());
	// close the stream
	fos.close();
}

Die Kommentare da sagen mir gar nichts. Die hätte man sich auch sparen können. Besser ist sowas:

public String getSettingsAsString() {
	List settings = getSettingsAsList();
	StringBuffer sb = new StringBuffer();
	
	// This loop is fairly complex. On startup we put the iterator of our list
	// into the variable "i". Also on startup we get the first entry out of our
	// Iterator and put that into "s". The others parts of the loop shall be
	// obvious.
	for(Iterator i = settings.iterator(),
			Setting s = (Setting)i.next(); i.hasNext(); s = (Setting)i.next()) {
		// We're entering the loop-body
		sb.append(s.toString());
	}
	
	return sb.toString();
}

Die Methode ist wunderbar klar und lesbar, die einzige unübersichtliche Stelle (bei der ich mir nichtmal sicher bin, ob die so kompiliert wird) wird von einem Kommentar erläutert.
Ein JavaDoc-Kommentar ist an dieser Stelle wirklich überflüssig, da der Methodenname gut genug gewählt ist, um Sinn und Zweck der Methode zu erklären.

[ehli75]

Auch wenn die Methode klein und ohne javaadoc nett ausschaut mach ich die javadoc-Kommentare rein ... 1.hab ich das Zeugs dann in meiner automatisch erzeugten Doku und 2. werden die Daten mir automatisch in eclipse presentiert, sobald ich mit der Maus drüber gehe.
Bei den Kommentaren innerhalb der methode hast du mich etwas falsch verstanden ... ich schreibe nciht für jedes Kommando ein Kommentar ... nur wenn es nötig ist (bitte jetzt nicht solche Sprüche wie: Der Code ist die Doku - hast du schon mal fremden Code ohne Kommentare gelesen ???)

Und dann noch gleich ne Kritik an deinem Beispiel ... auch als Prameter in einer Methode sollte man sprechende namen vergeben (und nicht sowas wie File f). Wenn du eine längere Methode hast, wirst du dich (oder jemand, der deinen Code verstehen muss sich) irgendwann fragen, was denn f ist.

[pago]

Ich hab oft genug fremden Code gelesen (habe schon ein paar "Hacks" für das wBB geschrieben - es ist wirklich die Hölle).
Code, der so kommentiert ist, wie ich es im 2. Beispiel gezeigt habe, habe ich schon häufiger bei Anfängern gesehen, denen gesagt wurde, dass Kommentare immer gut sind.
Daher nur ein Gegenbeispiel.

Die Anzeige des JavaDoc in Eclipse/NetBeans etc. ist dann hilfreich, wenn die Verwendung der Methode nicht direkt klar ist. Bei meinen Beispielen steht im Kommentar das gleiche, wie der Methodenname suggeriert. Folglich ist der Kommentar überflüssig (wie die Kommentare beim 2. Beispiel im Code der Methode).

Zu deiner Kritik: Das könnte ein Argument sein, muss es aber nicht. Wenn ich in meinem Code konsequent dabei bleibe und es vielleicht sogar in einer Dokumentation der Formatierung erwähne, dann sind solche kürzel durchaus machbar.
So wie ich den Index eines Arrays in einer For-Schleife auch grundsätzlich mit dem wenig selbsterklärendem Namen "i" ausstatte. Wenn in der Schleife noch eine For-Schleife vorkommt, dann heißt die grünsätzlich "j" (obwohl ich hier gestehen muss, dass ich versuche mir das abzugewöhnen - nette Idee wäre "n"). Das Iterator-Objekt habe ich übrigens auch "i" genannt - ebenfalls eine meiner Konventionen.
Genauso kann ich vereinbaren: Wenn in einer Methode nur ein "File"-Objekt vorkommt, dann wird dieses mit "f" bezeichnet.
Wenn ich konsequent dabei bleibe, dann ist das legitim und übersichtlich. Wenn ich natürlich mal dies mal das mache sinkt die Lesbarkeit erheblich.

Um einige meiner Kürzel zusammenzufassen (und das ich das überhaupt kann, sagt schon viel über die Konsistenz der Verwendung aus
i = Index einer For-Schleife / Iterator
j = Zweite Ebene einer For-Schleife (kommt so gut wie nie vor)
n = Dritte Ebene einer For-Schleife (kommt so gut wie nie vor)
s = String
fos = FileOutputStream
fis = FileInputStream
sb = StringBuffer / StringBuilder (5.0)

Solange ich niemals etwas wie

Map s = new HashMap();

einbaue und mich an meine Reglungen halte ist das ganze kein Problem.
Ferner sind diese Kürzel bei mir immer nur lokale Variablen, selten Parameter (wenn Parameter dann nur dann, wenn Zweck in der Methode trotzdem klar ist - im Falle von "f" sollte klar sein, dass das die Datei ist, die beschrieben werden soll).

Bei Sachen wie:

public void copySettings(File f, File f2);

wirst du auch bei mir nicht finden.

Da verwende ich dann auch sowas:

public void copySettings(File fromFile, File toFile);

Aber das sind so Dinge, über die man sich streiten kann. Wie gesagt bin ich der Meinung, dass auch Kürzel verwendet werden können, solange die Kürzel konsequent verwendet werden und eventuelle Mitentwickler über diesen Teil der Konventionen in Kenntnis gesetzt wurden (für mich ist das alltäglich, so dass ich mich mit Sicherheit nie fragen werde, was denn nun "f" ist).

[dyrathror]

Moin,

wie wäre es denn einfach mit dem offiziellen Styleguide?
Java Coding Styleguide

Und dann noch einen Codeformatter (z.B. den eingebauten von Eclipse) dementsprechend anpassen.

Gruß
Stephan

[Ben]

Zitat von ehli75

Auch wenn die Methode klein und ohne javaadoc nett ausschaut mach ich die javadoc-Kommentare rein ... 1.hab ich das Zeugs dann in meiner automatisch erzeugten Doku und 2. werden die Daten mir automatisch in eclipse presentiert, sobald ich mit der Maus drüber gehe.

Exakt. Genau das ist auch mein Grund warum ich so verfahre.

Zitat von ehli75

auch als Prameter in einer Methode sollte man sprechende namen vergeben (und nicht sowas wie File f). Wenn du eine längere Methode hast, wirst du dich (oder jemand, der deinen Code verstehen muss sich) irgendwann fragen, was denn f ist.

Kann ich ebenfalls nur zustimmen. Es gibt ja nicht schlimmeres, als wenn man irgendwann a, f1 und f2, x und i, j und k hat ... Hilfe ...

Präzise, selbsterklärende Namen sind meiner Ansicht nach absolute Pflicht für jede Art von lesbaren Code

Grüße Ben.

[dyrathror]

Ihr habt meine absolute Zustimmung zu gut lesbarem Code

Zu den Zeiten als ich noch in C programmiert habe konnte ich meinen eigenen
Code oft schon nach Tagen nicht mehr verstehen

Jetzt wird alles mit javadoc anständig dokumentiert, sprechende Variablennamen gewählt und auch auf ein vernünftiges Format geachtet, auch wenn's länger dauert. Hält halt auch länger

Viele Grüße
Stephan

[Ben]

Zitat von dyrathror

auch wenn's länger dauert. Hält halt auch länger

Bringt es irgendwie auf den Punkt