Für Kommentierung gibt es keine einfachen Regeln.
D.h. es gibt schon Regeln. Aber das ist eben ziemlich komplex.
Um es esoterisch auszudrücken:
Verschiedene "Kräfte" wirken auf die Kommentierung:
- zu wenig Kommentierung erschwert später das Verständnis.
- zu viel Kommentierung erzeugt Info-Rauschen, so dass es später mühsam wird, das wichtigste vom unwichtigen zu trennen.
- ausserdem wird code öfters mal umgeschrieben. Wenn viele Kommentare da stehen, muß bei Änderungen evtl. viel editiert werden. Das Problem von vielen Kommentaren ist nämlich, dass sie versionsmässig nicht in Sync mit dem code sind.
Sprechende Variablennamen sind im Prinzip auch schon als Kommentare anzusehen. Und zwar als eine effiziente Art von Kommentaren.
Auch bei Variablennamen gibt es keine einfachen, globalen Regeln. Z.B. galt v.a. in Windowsumgebungen "ungarische" Notation als das non plus ultra. Bei ungarischer Notation ist eine Abkürzung des Typs der Variable Teil dieses Variablennamens. Für z.B. Java gilt aber ungarische Notation als unsinnig. Zumindest nicht so wie ungarische Notation in den 90ern verstanden wurde. Um die Verwirrung komplett zu machen, behauptet man jetzt das ungarische Notation eigentlich nicht so benutzt wurde, wie sie eigentlich intendiert war:
http://www.joelonsoftware.com/articles/Wrong.htmlIch kenne ein paar Großsprecher, die mit quasi-religiöser Überzeugung ungarische Notation als Lösung von Entropie-Problemen in Notes propagiert haben. Ich hab davon nie viel gehalten. Offenbar haben sie also ein falsch verstandenes Konzept verkauft.
Für ein Team von Entwicklern sollten natürlich Regeln da sein. Trotzdem sollte man aber die Regeln für Kommentierung kritisch hinterfragen. Ich hab da schon so viel Unsinn gehört.
Der Zweck ist ja klar: Kommunikation mit dir oder einem anderen Entwickler über den Code. Adressat ist wichtig: code-Kommentare sind für Entwickler.
Nur treffen da eben 2 komplexe Dinge aufeinander. Source-Code und das menschliche Verständnis von Dingen. Wir sehnen uns zwar nach Übersichtlichkeit und Einfachheit. Zu einfache Regeln werden aber der Aufgabe vielleicht nicht gerecht.
Hier ist übrigens eine kleine, dumme eben geschriebene Methode von mir mit Kommentaren (zwar in Java, aber egal):
/**
*
* retrieves all open stock offers by an user from the database.
*
* @param idUser. Id of user in rdbms.
* @see de.aja.fussi.dao.StockOfferDao#getStockOfferByIdUser(long)
* @return a map of all open offers by an user. key-syntax: idStockDescr + "#" + price.
*
*/
public Map getStockOfferByIdUser(long idUser) {
Map mapOffersUserUnsorted = null; // return value.
// call db-layer
List stockOffersUser = (List)getSqlMapClientTemplate().queryForList("getStockOfferByIdUser", new Long(idUser));
if (stockOffersUser.size() == 0) {
return new NullStockOffers(); // NullObjectPattern ---> back to caller.
} else {
mapOffersUserUnsorted = new HashMap();
}
// put list of offers in the map to return to caller
Iterator it = stockOffersUser.iterator();
while (it.hasNext()) {
StockOffer stockOffer = (StockOffer) it.next();
mapOffersUserUnsorted.put(stockOffer.getIdStockDescr() + "#" + stockOffer.getPrice(), stockOffer);
}
return mapOffersUserUnsorted;
}
Ich kommentiere hier z.B.:
- Als erstes eine Zusammenfassung der Intention.
- Der übergebene Parameter.
- Das was sie zurückgibt.
- Von mir selbst eingeführte Konventionen. Etwa wie sich der Key der Map zusammensetzt.
- wenn zwischendrin ein Return kommt (gibts ja auch in Formelsprache)
- Design Patterns
- Die Methode hat eine gewisse Sequenz: 1. Wird auf Datenbank zugegriffen. 2. Dann werden die Rückgabewerte in eine bestimmte Datenstruktur gebracht (nachbearbeitet).
Vor jedem dieser logischen Abschnitte steht ein kurzer Kommentar.
Irgendwelche Meinungen? Auch von anderer Stelle.
Gruß Axel
