Suche Kommentar HowTo

6 Beiträge18.07.2007Archiviert
jeipack18.07.2007 · Beitrag #14197
Avatar
Mitglied seit: 07.03.2007
Forenbeiträge: 448
Besuche: 1258
Hi
Kennt wer von euch ein gutes HowTo zum Kommentieren von Programmcode?
Normalerweise würde ich sowas ja selbst suchen, doch leider kommen die Wörter Kommentar/Kommentieren bei 99% aller Howtos im Netz vor..

thx
jeipack
squeez18.07.2007 · Beitrag #14200
Mitglied seit: 06.04.2005
Forenbeiträge: 687
Besuche: 668
Guten Tag

In der modernen Softwareentwicklung spricht man von sogenannten "Code Smells" [1] und den passenden Refactorings dazu.
Mitunter gehört auch Kommentar zu dieser Kategorie. Kommentar ist zwar wichtig, sollte aber das "wie" beschreiben und nicht das "was". Das "was" sollte durch den Programmcode erkennbar sein. Ist dies nicht der Fall, so ist das gewählte Design zu überarbeiten.


hth
Marco

[1]http://wiki.java.net/bin/view/People/SmellsToRefactorings
jeipack19.07.2007 · Beitrag #14205
Avatar
Mitglied seit: 07.03.2007
Forenbeiträge: 448
Besuche: 1258
Hey squeez
Interessant, danke
Allerdings verwirrt mich das gerade ein bisschen. Bis jetzt Beschrieb ich meistens das "Was" (z.B. diese Methode ermittelt den Durchschnittswert der Werte x und y aus der Tabelle soundso), denn das "Wie" wird ja durch den Code erklährt. Nur wenn es sehr komplexe Methoden sind schreibe ich auch wenige Worte zum "Wie".

Sollte es noch andere Interessieren:
http://industriallogic.com/papers/smellstorefactorings.pdf
steht aber in etwa das gleiche wie im obrigen Link drin.

Gruss
squeez19.07.2007 · Beitrag #14208
Mitglied seit: 06.04.2005
Forenbeiträge: 687
Besuche: 668
Sorry, es sollte "weshalb" heissen und nicht "wie".


z.B. diese Methode ermittelt den Durchschnittswert der Werte x und y aus der Tabelle soundso

Dies sollte jedoch aus dem Namen der Methode hervorgehen. Die Smells hängen alle etwas zusammen. Schau dir auch noch die anderen an. ZB. "Uncommunicative Name" und "Type Embedded in Name" gelten auch für Methodennamen...

Marco

jeipack19.07.2007 · Beitrag #14209
Avatar
Mitglied seit: 07.03.2007
Forenbeiträge: 448
Besuche: 1258
Achja logisch why = weshalb.

Ja Methodennamen sind sehr wichtig, da achte ich auch recht gut drauf. Allerdings reicht es nicht immer und zweiseitige Methodennamen sind dann auch ein bisschen unhandlich ^^. An das "weshalb" hab ich bis jetzt noch nicht gedacht, obwohl es ja für spätere Untersuchungen des Codes sehr hilfreich wäre.

jeipack
squeez19.07.2007 · Beitrag #14222
Mitglied seit: 06.04.2005
Forenbeiträge: 687
Besuche: 668
Guten Tag


Allerdings reicht es nicht immer und zweiseitige Methodennamen sind dann auch ein bisschen unhandlich ^^.


Ich gehe mal davon aus, dass wir von objektorientierter Programmierung sprechen. Ein Methodenname kann also mehrfach überladen sein.

Nehmen wir an, wir haben folgende Codestruktur:
[command]
class Customer
{
//Fügt den Artikel x einem Kunden hinzu
void addArticle (int x) {
...
}

//Fügt dem Kunden einen Mietbetrag hinzu
void addRental (long x) {
...
}
}
[/command]

In der obigen Form sind beide Kommentare notwendig. Ohne sie wissen wir nicht genau was 'x' darstellt. An dieser scheinbar einfachen Klasse jedoch ist einiges falsch, was ich nachfolgend schrittweise begründen werde. Wir werden sehen, dass bei einem sauberen Design solche Kommentare überflüssig werden.

Zunächst einmal ändern wir x in einen sinnvollen Bezeichner:
[command]
class Customer
{
//Fügt den Artikel article einem Kunden hinzu
void addArticle (int article) {
...
}

//Fügt dem Kunden einen Mietbetrag rental hinzu
void addRental (long rental) {
...
}
}
[/command]

An dieser Stelle können wir uns überlegen, ob die Klasse Customer überhaupt den Datentyp für die Artikelnummer und denjenigen für die Miete kennen muss. Wenn wir davon ausgehen, dass zu einem späteren Zeitpunkt die Artikelnummer durch einen String ersetzt werden könnte, müssten wir unseren Code an dieser Stelle anpassen. Also erstellen wir eine unabhängige Klasse, welche die notwendigen Datenstrukturen und die Methoden zum Zugriff enthält.
[command]
class Customer
{
void addArticle (Article article) {
...
}

void addRental (Rental rental) {
...
}
}
[/command]

Ab diesem Zeitpunkt werden die Kommentare überflüssig und wir lassen sie weg. Wenn nun jedoch der Parameter bereits die Information darüber enthält, was die Methode verarbeitet, ist diese Information im Methodenname redundant und kann entfernt werden:

[command]
class Customer
{
void add (Article article) {
...
}

void add (Rental rental) {
...
}
}
[/command]

Wir haben dadurch keinen Informationsverlust erlitten.

Wenn nun ein Customer sowohl die Ausleihe wie die Artikel kennt, muss dieser diese intern verknüpfen. In diesem Fall verletzen wir das [[GRASP]] Pattern 'High Cohesion' welches besagt, dass eine Einheit (Methode oder Klasse) nur genau das tun sollte, was sie tun muss und nicht mehr. Wir stellen fest, dass die Klasse Customer nichts von einer Miete wissen muss und entfernen diese aus der Klasse.

[command]
class Customer
{
void add (Article article) {
...
}
}
[/command]

Wir gehen nun davon aus, dass die Klasse Rental den Betrag der Miete berechnen soll und fügen deshalb der Klasse Customer eine Methode hinzu, welche die dem Kunden zugewiesene Artikel zurück gibt:

[command]
class Customer
{
void add (Article article) {
...
}

List<Article> get () {
...
}

}
[/command]

Die Klasse Rental:
[command]
class Rental
{
Customer customer;

Summary calculate ()
{
...
List<Article> articles Customer.get ();
...
}
}
[/command]




Mit diesen Schritten sind wir von einem mieserablen Design zu einem gelangt, das den Anforderungen der objektorientierten Programmierung genügt (über alles andere kann man sich streiten).


An das "weshalb" hab ich bis jetzt noch nicht gedacht, obwohl es ja für spätere Untersuchungen des Codes sehr hilfreich wäre.

Dokumentation ist eben für den Programmierer, und nicht für den Kunden :-)


hth
Marco