qualitativ hochwertiger Programmcode...

junix

Äh Marcus: hast du zu meinem Obigen Statement (26 Aug 2003 10:59) noch irgendwelche korrigierende Kommentare, oder kann man das so stehenlassen? Würde mich wirklich interessieren, denn ich stell mir die Frage "Was ist qualitativ guter code" auch desöfteren.

-junix

shoat

Hallo volkard!

volkard schrieb:

void Mobile::go(int richtung)
{
   switch(richtung)
   {
      case 0: goNorthWest(); break;
      case 1: goNorth(); break;
      case 2: goNorthEast(); break;
      case 3: goWest(); break;
      case 4: ; break;
      case 5: East(); break;
      case 6: goSouthWest(); break;
      case 7: goSouth(); break;
      case 8: goSouthEast(); break;
   }
}
void goNorthWest()
{
   x-=1;
   y-=1;
}
//..und noch sieben funktionen
//(1*10+8*2)/9==2.9 zeilen pro funktion

zerfällt bei langem anstarren zu

void Mobile::go(int richtung)
{
   int rx=richtung%3-1;
   int ry=richting/3-1;
   x+=rx;
   y+=ry;
}
//4 zeilen pro funktion, schlechter gemetirkt.

Du hast wirklich vollkommen recht, dass es die obere Lösung vollkommener Schwachsinn ist. Und natürlich ist die untere Lösung viel besser. Aber in der Form kann man sie meiner Meinung nach unmöglich belassen. So würde ich sie einstellen.

public class Mobile
{
    protected int posX, posY ;

    ...

    /**
     * Versetzt das Mobile in die angegebene "richtung".
     * @param 	richtung    Gibt die Richtung an. Dabei bedeutet richtung%9 
     *                        gleich 0 linksunten, 1 unten, 2 rechtsunten, 
     *                        3 links, ...
     */
    public void go (int richtung)
    {
        this.posX += richtung%3-1 ;
        this.posY += richtung/3-1 ;
    }
}

So finde ich es besser. Damit schneidet die Funktion (denke ich?) auch bei Metriken gut ab und nichts von Deiner guten Lösung geht verloren.

double* find(double toFind,double* arr,int size) 
{ 
   for(int i=0;i<size;++i) 
      if(arr[i]==toFind) 
         return &arr[i]; 
   return 0; 
}

Guter Algorithmus, aber auch zu dieser Funktion (zumindest, wenn sie public ist) gehört meinesachtens eine Schnittstellenbeschreibung!

Warum? Ganz einfach. Wenn Dritte Deinen Code nutzen sollen, dann fällt ihnen dies viel leichter, wenn die nutzbaren Schnittstellen verständlich beschrieben sind. I. d. R. dauert es viel länger, wenn man erst den Quell-Code anschauen und verstehen muss.

Oder was meinst Du dazu?

Ciao
shoat

Marc++us

junix schrieb:

Äh Marcus: hast du zu meinem Obigen Statement (26 Aug 2003 10:59) noch irgendwelche korrigierende Kommentare, oder kann man das so stehenlassen? Würde mich wirklich interessieren, denn ich stell mir die Frage "Was ist qualitativ guter code" auch desöfteren.

Du stellst am Schluß die Frage "wer denkt schon so?" - und da muß ich sagen: "zu viele".

Du hast natürlich bzgl. der Wartbarkeit recht, trotzdem gibt es ja eine Wertigkeit, irgendwann muß man mal eine Entscheidung "entweder so oder so" treffen - und da wichte ich die Fehlerfreiheit als Ziel immer höher.

Es hat noch so einen Nebeneffekt, weil die Punkte nicht wirklich getrennt sind: schlanke und übersichtliche Designs ermöglichen oft weitgehend fehlerfreie Programme (also: Algorithmus und Gesamtidee funktioniert wie gewünscht, aber es gibt hier und da mal kleine Lücken, oftmals im Zusammenhang mit der GUI). Und gleichzeitig sind diese Programme auch gut wartbar. Und Wartbarkeit (auch im Sinne von Erweiterungen) geht auf dann auch Hand in Hand mit der Wiederverwendung vorhandener Klassen/Objekte der Applikation.

Also könnte man die Punkte gleich wichten? Und da sage ich vor meiner Erfahrung mit anderen Entwicklern ganz klar "Nein". Wenn mich einer fragt, sage ich immer "Fehlerfreiheit geht vor".

Weißt Du warum? Softwareentwickler sind in ihrem Herzen alles wahnsinnige Spielkinder. Wenn ich einem Entwickler als wichtiges Ziel zu erkennen gebe, daß mir Wartbarkeit und/oder Wiederverwertbarkeit wichtige Ziele sind, so baut er mir ein riesiges Programm mit Klassen und Mustern und Interfaces und Komponenten, das von Mondflügen bis zur Waschmaschine alle Anwendungen abdecken kann, so eine Art Framework. Der eigentliche Auftrag des Programms wird dann als "Konfigurations- und Anpassproblem" definiert, "das machen wir noch". Natürlich ist es interessant so ein Framework zu entwickeln, elegante Lösungen zu definieren, usw. Macht mir auch mehr Spaß also so ein doofes Programm zu schreiben. Wenn 2 oder 3 Leute aber so arbeiten, treibt es einen in den Wahnsinn und man muß es rigoros unterbinden.

Ich finde

http://www.c-plusplus.net/titelanzeige.php?ISBN=3826613260

ist dazu ein sehr erhellendes Buch, das meine Erfahrungen auch in einigen Punkten bestätigt hat.

Zu den Metriken:
Ich teile volkards Meinung, daß sie nichts taugen. Die mir bekannten Metriken messen bloß, wie geschwätzig ein Entwickler ist. In Bezug auf die Qualität seines Codes können sie keine Aussage treffen.

Ich glaube, Metriken sind eher ein Ausdruck der Hilflosigkeit (oder meinetwegen auch Überfroderung) des Führungspersonals, wenn es darum geht, die Arbeit der Entwickler zu beurteilen. Man frage sich selbst: Wenn bekannt ist, daß die "Qualität" meiner Arbeit anhand von Metriken ermittelt wird - wovon dann vielleicht meine Aufstiegschancen, mein Gehalt o.ä. abhängen - wie werde ich arbeiten, gut oder mit möglichst viel Code? So ein Quatsch!

Guter Algorithmus, aber auch zu dieser Funktion (zumindest, wenn sie public ist) gehört meinesachtens eine Schnittstellenbeschreibung!

Warum? Ganz einfach. Wenn Dritte Deinen Code nutzen sollen, dann fällt ihnen dies viel leichter, wenn die nutzbaren Schnittstellen verständlich beschrieben sind. I. d. R. dauert es viel länger, wenn man erst den Quell-Code anschauen und verstehen muss.

Das sehe ich nicht ganz so. Ich finde es oft leichter, einen guten(!) Code zu verstehen, als die Schnittstellenbeschreibung zu lesen. Das trifft auf find() ebenso wie auf Mobile::go() zu. Allerdings ist der Code in beiden Fällen nicht optimal. Im Falle von find() fehlt eine Fehlerbehandlung (arr darf nicht 0 sein). BTW: In einem C++-Projekt gehört sich etwas wie find() natürliche ohnehin nicht.

Im Falle von Mobile::go() sollte der Parameter nicht vom Typ int sondern Mobile::Richtung sein, der natürlich ein passender enum wäre. Damit beschreibt der Code die Funktion schon verdammt gut.

Trotzdem gehört für mich eine Schnittstellenbeschreibung dazu. Diese allerdings sollte nichts enthalten, was man aus der Signatur der Funktionen entnehmen kann. Und dann bleibt bei den Beispielen wohl nicht allzu viel übrig. Natürlich ist eine Schnittstellenbeschreibung für jede Funktion angemessen, nicht nur für die public-Schnittstelle.

Stefan.

Marc++us

Wobei das auch relativ ist und von der Anwendung (bzw. vom Kontext) abhängt.

Methoden wie

bool Sprite::checkForCollision(const Sprite& otherSprite)
void Customer::loadFromXMLFile(const std::string& filename) throw IOErrors::LoadException;

sind nur noch mit wirklich zusätzlichen Kommentaren trivial kommentierbar, d.h. ein

/* Prüft ob eine Kollision zwischen dem aktuellen Spriteobjekt und otherSprite
   aufgetreten ist, liefert true im Kollisionsfall */
/* Lädt Kundenobjekt aus der XML-Datei, deren Name in filename übergeben wird.
   Bei einem Parsingerror wird eine Exception geworfen */

liefert definitiv keinen Zusatznutzen.

Daniel E.

DStefan schrieb:

Trotzdem gehört für mich eine Schnittstellenbeschreibung dazu. Diese allerdings sollte nichts enthalten, was man aus der Signatur der Funktionen entnehmen kann. Und dann bleibt bei den Beispielen wohl nicht allzu viel übrig. Natürlich ist eine Schnittstellenbeschreibung für jede Funktion angemessen, nicht nur für die public-Schnittstelle.

Liest diese Schnittstellenbeschreibung wirklich jemand?
Aus der Sicht desjenigen, der den Code an- und verwenden möchte ist Fließtext in einer gesprochenen Sprache selten semantisch so schön eindeutig, wie der Code einer Programmiersprache. Um die Missverständlichkeiten aus dem Weg zu räumen liest er den Code.
Und der, der den (im Idealfall kaputten) Code zu warten oder wiederherzustellen hat, wittert sowieso hinter jeder Zeile Betrug und glaubt gar nichts.

Helium

Hallo Helium!

Wäre toll, wenn Du mir kurz erklären könntest, was es mit Pre- und Postkonditionen auf sich hat. Ich habe davon noch nie was gehört und auch in den Büchern, die ich lese, gibt es darauf bisher keinen Hinweis. Ich bin auch für einen Link sehr dankbar!

Nachdem Markus mit seinem Zitat alles erklärt hat kann ich wohl nichtmehr viel beitragen.

C++, du scheinst scheinbar Java zu verwendent, da ist es genauso, bitet keine sprachseitige Unterstützung für solche Tests.

Vorbedingungen werden in C++ deshalb meist so formuliert:

double wurzel (double radiant)
{
   assert (radiant >= 0);  // Vorbedingung
   // algorithmus, der die wurzel berechnet und zurückgibt
}

In diesem Fall ließ sich sogar eine Nachbedingung formulieren, wie

assert(ergebnis * ergebnis == radiant);

Das problem ist, das man häufig mehrere Austrittspunkte hat und deshalb an verschiedenen Stellen die Bedingungen stellen müsste, was selbst wiederum fehleranfällig ist. Man verändert den Code und vergisst dann mögliche neue Kondidtionen an einigen Stellen.

Invarianten Funktionieren in etwa so: Angenommen du hast eine Klasse Datum dann könnte eine Methode invariant so aussehen:

void invariant ()
{
   assert (m_monat >= 1 && m_monat <= 12);
   assert (m_tag >= 1 && m_tag <= 31);
}

Invarianten werden für gewöhnlich nach jedem Aufruf einer Methode ausgeführt. Einige Sprachen automatisieren das, weshalb es in solchen Sprachen auch üblich ist.

Wie schon erwähnt heißt das ganze Design-by-Contract. Der Vertrag mit dem Aufrufer besteht quasi darin, dass man sagt, wenn er korrekte Daten liefert, liefert der Aufgerufene ein korrektes Ergebnis.

Da du nicht nach Unit-Tests gefragt hast scheinst du dazu genug Material zu haben. Sowas wie Test-Driven-Design.

shoat

DStefan schrieb:

Zu den Metriken:
Ich teile volkards Meinung, daß sie nichts taugen.

Ich habe auch nie behauptet, dass ich Metriken gut finde, denn ich habe nicht genug Ahnung, um mir schon eine eigene Meinung zu erlauben. Und ich nehme zur Kenntnis, dass die Praxis (damit meine ich Euch) nicht sehr begeistert ist!

Später komme ich bestimmt noch darauf zurück. Solange müßt ihr euch leider noch gedulden!

Es ist aber sehr gut, dass ihr mich schon so früh auf die Probleme gestoßen habt. Danke dafür!

shoat schrieb:

Wenn Dritte Deinen Code nutzen sollen, dann fällt ihnen dies viel leichter, wenn die nutzbaren Schnittstellen verständlich beschrieben sind. I. d. R. dauert es viel länger, wenn man erst den Quell-Code anschauen und verstehen muss.

DStefan schrieb:

Das sehe ich nicht ganz so. Ich finde es oft leichter, einen guten(!) Code zu verstehen, als die Schnittstellenbeschreibung zu lesen. Das trifft auf find() ebenso wie auf Mobile::go() zu.

Ok! Da Du diese Aussage auf die beziehst, nehme ich sie so hin. Mir geht es manchmal auch so!

Bei Volkards Mobile::go habe ich zum Verstehen jedenfalls ca. 1-2 min gebracht habe. Wäre allerdings in einem Kommentar irgendwie soetwas wie:

// aktueller Standort des Mobile = X. 
// Wähle eine Richtung (==Ziffer) zum Verändern des Standorts aus, wobei gilt:
// 6 7 8
// 3 X 5
// 0 1 2

gestanden, hätte nur durch hinschauen, dass System sofort verstanden. Ich hätte es zwar nicht verstanden wie die Funktion funktioniert, aber ich hätte sie nutzen können!

Genau dass ist der Punkt! Uns (Studenten) wird von allen Seiten beigeracht, wenn wir von Dritten implementiere Funktionalitäten nur nutzen wollen: "Schau nicht den Code an, sondern nur die Beschreibung der Schnittstelle." Was soll ich machen, wenn es keine (gute) Schnittstellenbeschreibung gibt?

Wenn man allerdings einen Code "warten" soll, Weiterentwicklen will oder auf Fehlersuche ist, dann sieht es natürlich ganz anders aus! Dann muss man sich den Code sowieso genau anschauen, deswegen wäre es vielleicht sehr gut, wenn man eine Unterscheidung zwischen:
Kommentare, die auf Nutzer der Funktionalität des Codes abzielen
Kommentare, die auf Prüfer/Weiterentwickler des Codes abzielen

Natürlich ist es ganz klar, dass für letzter ganz andere Sachen wichtig sind. Zu qualitativ hochwertigem Code gehört aber beides dazu!

Allgemein muss ich aber sagen, dass - meiner subjektiven Meinung nach - viel zu wenig kommentiert wird. Ich weiß nicht, wie es bei Euch in der Praxis aussieht. Aber alle, die ich kenne, sind mit den Kommentierungen von fremden Code (z. B. von Libs) oft unzufrieden. Da wird z. B. Wissen vorausgesetz, dass man einfach nicht hat oder es kommen Pseudo-Kommentare raus, wie:

...
/** ...
 * @param xyz  dies ist der Parameter xyz der Funktion hasteNichtGesehen
 */
public void hasteNichtGesehen (MysticUnknown xyz) { ... }
...

DStefan schrieb:

Allerdings ist der Code in beiden Fällen nicht optimal. Im Falle von find() fehlt eine Fehlerbehandlung (arr darf nicht 0 sein). BTW: In einem C++-Projekt gehört sich etwas wie find() natürliche ohnehin nicht.

Die Fehlerbehandlung vergesse ich doch immer zu gern. Du hast natürlich vollkommen recht.

DStefan schrieb:

Im Falle von Mobile::go() sollte der Parameter nicht vom Typ int sondern Mobile::Richtung sein, der natürlich ein passender enum wäre. Damit beschreibt der Code die Funktion schon verdammt gut.

Ich weiß zwar nicht, was ein enum ist, aber ich glaube Dir, dass es möglich ist, durch den Code die Funktion noch besser zu beschreiben.
(Vielleicht bekomme ich ja ein kleines Quellcode-Fragment im Bezug auf Mobile::Richtung? Nur, wenn Du Zeit und Lust hast!!!)

DStefan schrieb:

Trotzdem gehört für mich eine Schnittstellenbeschreibung dazu.

Dann sind wir ja einer Meinung!

DStefan schrieb:

Diese allerdings sollte nichts enthalten, was man aus der Signatur der Funktionen entnehmen kann. Und dann bleibt bei den Beispielen wohl nicht allzu viel übrig.

Bin mir hier nicht ganz sicher, was Du mit Signatur meinst - den Prototypen?
Da ich keine Ahnung hab, was man dem "enum" alles entnehmen kann, würde ich vorerst auf meine Fassung besstehen, da ich mir den Quellcode als reiner Nutzer des Codes nicht anschauen soll. (siehe auch unten)

DStefan schrieb:

Natürlich ist eine Schnittstellenbeschreibung für jede Funktion angemessen, nicht nur für die public-Schnittstelle.

Denn Einwand mit dem public hatte ich nur deswegen gebracht, weil für mich als Javaer alles eine Klasse ist. Damit habe ich von außen nur Zugriff auf den public-Bereich. Alles andere interessiert mich in diesem Zusammenhang erst einmal nicht.

Für die interne Wartung einer Klasse sind natürlich auch alle anderen Schnittstellen sauber zu beschreiben.

Was hälst Du davon?
Kommentare, die auf Nutzer der Funktionalität des Codes abzielen im public-Bereich und der allgemeinen Programmbeschreibung (meint Klassenbeschreibung)
== ziemlich ausführlich / dummy-tauglich
(in Java sind dass die /** */ Kommentare fürs javadoc)

Kommentare, die auf Prüfer/Weiterentwickler des Codes abzielen überall
== aber nur da, wo man es auch wirklich braucht / insider-tauglich
das meiste sollte dem Code selber entnommen werden können)

Vielen Dank für den Beitrag!

Ciao
shoat

Shade Of Mine

shoat schrieb:

(Vielleicht bekomme ich ja ein kleines Quellcode-Fragment im Bezug auf Mobile::Richtung? Nur, wenn Du Zeit und Lust hast!!!)

ein enum ist nur eine aufzaehlung.

statt
m.go(3);
schreibt man
m.go(GO_RIGHT);
oder so.

ein enum ist ganz simpel:

enum RICHTUNG
{
  GO_RIGHT=1,
  GO_LEFT=2,
  GO_UP=3,
  .
  .
  .
};

natuerlich muessen die zahlen stimmn (und ich bin jetzt zufaul mir den code anzusehen um die richtigen zahlen herauszulesen. aber das prinzip sollte klar sein

junix

<@Marcus>
Danke, damit hast du bestätigt, was ich mir bereits gedacht habe nach deiner Andeutung "aus psychologischen Gründen". Das Buch werd ich mir mal zu Gemüte führen, sieht interessant aus (auch wenn ich nicht Projektleiterpositionen einnehmen kann/will *g*).

Ich glaube dir zwar, dass zu viele so denken wie ich es angetönt hatte, aber ich denke, man sollte nicht die "Regeln" an denen Anpassen sondern ein Umdenken lancieren. Klar. Man kann alte Wölfe nicht dazu bringen, aus der Hand zu fressen, aber den Nachwuchs müsste man doch eigentlich mit neuem Denken aufziehen können. Wobei das bestimmt ein Prozess ist, der länger dauert.

Das Problem ist, beim Senken der Priorität der Wartbarkeit, dass dies auch misverstanden werden könnte...
/@Marcus

(zu Shades Beitrag)
Das schöne an Shades Enum-Lösung sind eigentlich 2 Nebeneffekte:

Das programm wird wieder selbstdokumentierende
Durch das enum-Feld kann man eine Typensicherheit erstellen, was die Fehleranfälligkeit des Codes wieder verkleinert.

-junix

shoat

Marc++us schrieb:

Wobei das auch relativ ist und von der Anwendung (bzw. vom Kontext) abhängt.

Methoden wie
bool Sprite::checkForCollision(const Sprite& otherSprite)
void Customer::loadFromXMLFile(const std::string& filename) throw IOErrors::LoadException;
sind nur noch mit wirklich zusätzlichen Kommentaren trivial kommentierbar, d.h. ein
/* Prüft ob eine Kollision zwischen dem aktuellen Spriteobjekt und otherSprite
   aufgetreten ist, liefert true im Kollisionsfall */
/* Lädt Kundenobjekt aus der XML-Datei, deren Name in filename übergeben wird.
   Bei einem Parsingerror wird eine Exception geworfen */
liefert definitiv keinen Zusatznutzen.

Ich persönlich würde es trotzdem dazuschreiben, wenn es sich um public-Funktionen (s. o.) handelt.
Denn eine Schnittstellenbeschreibung sollte unbedingt immer gemacht werden!

Außerdem kann ich ja nicht wirklich wissen, was die Funktion macht, wenn ich mir den Code nicht genau anschaue. In diesen Fall ist es zwar unwahrscheinlich, aber könnte ja etwas fehlinterpretieren - man hat ja mit fremden Code schon genug erlebt. Also bin ich erst mal unsicher (zumindest, wenn es nicht gleich funktioniert). Wenn jetzt ein Fehler auftritt, dann weiß ich nicht woran es liegt, habe ich etwas falsch gemacht (eigener Fehler) oder habe ich nur etwas falsch verstanden (Verständnisfehler) oder ist der Fremd-Code einfach fehlerhaft (Fremd Fehler). Und so suche ich vor mich hin. Was wieder Zeit kostet. Vielleicht vertue ich mich auch noch beim Testen und dann ... (am Schluß komme ich dann vielleicht zu dem Schluß, dass es am Besten ist doch alles Selber zu programmieren.)

Ich denke Du hast verstanden worauf ich hinaus will!

Wenn allerdings genau dasteht was ein Funktion machen soll (== Schnittstellenbeschreibung), dann verlasse ich mich erst mal darauf - ich bin nicht unsicher. Und wenn dann Fehler auftreten, die nicht auftreten dürften, dann suche ich den Fehler wenigstens nicht bei mir!

( Ich bin mir natürlich auch dessen bewußt, dass es auch ein großes Problem darstellt leicht verständliche Kommentare zu schreiben! )

Naja! Mal schauen, ob ich alles so auf Blatt gebracht habe, wie ich es meine. Wenn nicht muss ich es halt nochmal kommentieren!

Vielen Dank für den Beitrag!

Ciao
shoat

shoat

Shade Of Mine schrieb:

shoat schrieb:

(Vielleicht bekomme ich ja ein kleines Quellcode-Fragment im Bezug auf Mobile::Richtung? Nur, wenn Du Zeit und Lust hast!!!)

ein enum ist nur eine aufzaehlung.
ein enum ist ganz simpel:

natuerlich muessen die zahlen stimmn (und ich bin jetzt zufaul mir den code anzusehen um die richtigen zahlen herauszulesen. aber das prinzip sollte klar sein

Danke für die Hilfe! Ich hatte mir schon sowas gedacht. In Java würde ich mir eine eigene Klasse schreiben, sowas wie:

public class Richtung
{
    public final static NORDWESTEN = 0 ;
    public final static NORDEN = 1 ;
    ...
}

Nochmal vielen Dank!

Wenn ich aber diese Richungsangaben nur einmal für das Mobile::go() benötige, dann muss man sich die Frage gefallen lassen, ob sich der Aufwand überhaupt mit dem enum überhaupt lohnt und nicht ein kurzer Kommentar die effektivere Lösung wäre.

Ciao
shoat

shoat

Daniel E. schrieb:

Liest diese Schnittstellenbeschreibung wirklich jemand?

Als reiner User eines Codes (Lib, etc.) lese immer zuerst die Schnittstellenbeschreibung. Bei vielen Libs hat man ja oft auch nicht mal die Wahl (z. B. bei den JDK's von Sun ).

Wie ich schon sagte, wenn ich den Code Warten / Prüfen / Weiterentwickeln muss bzw. will, dann sieht die Sache natürlich ganz anders aus!

Ciao
shoat

shoat

Helium schrieb:

Nachdem Markus mit seinem Zitat alles erklärt hat kann ich wohl nichtmehr viel beitragen.

Danke für das Beispiel! Es hat mir die Sache ganze nochmal verdeutlicht! Ich glaube mir ist jetzt klar, was damit gemeint ist! Ich finde die Sache sehr interessant. Mal sehen, wie ich das ganze in meine Arbeit integriere. Ich finde diesen Aspekt auf jeden Fall sehr hilfreich!

Helium schrieb:

Da du nicht nach Unit-Tests gefragt hast scheinst du dazu genug Material zu haben. Sowas wie Test-Driven-Design.

Den Ausdruck Test-Driven-Design habe ich zwar noch nicht gehört. Aber Du hast Recht. Ich habe vorerst recht viel Material. JUnit oder ein vergleichbares Opensource-Tool soll ein zentraler Bestandteil, des aufzubauenden Testframeworks, werden!

Viele Grüße!

Ciao
shoat

Puh! Das geht ja so schnell, da kommt man ja kaum mit dem Lesen nach!

Schnittstellenbeschreibungen:
Ich finde, man sollte die Signatur einer Funktion als Teil dieser Beschreibung ansehen. Und es ist der wichtigere Teil! Ich habe schon eine Million Kommentare gesehen, die gar nicht mehr zu der Funktion paßten, zu der sie gehörten. Klar, Schlamperei, aber damit muß man rechnen. Deshalb gilt für mich die goldene Regel, alles als Code zu schreiben, was man als Code schreiben kann, und Kommentare nur als zweite, nachrangige Instanz für Dokumentation zu sehen. Das gilt natürlich nicht nur für die Beschreibung einer Funktion, sondern auch für den Code innerhalb von Funktionen.

Den Unterschied (von shoat) zwischen Usern der Funktion und denen, die sie warten müssen kann ich eigentlich nicht nachvollziehen - jedenfalls nicht in diesem Kontext. Natürlich, letztere müssen sich die Innereien der Funktion ansehen, um z.B. einen Fehler zu finden. Aber das hat doch mit der Schnittstellenbeschreibung höchstens am Rande zu tun. Mir geht es darum Kommentare zugunsten des Codes in den Hintergrund zu rücken. Das ist für alle Entwickler, die damit umgehen müssen von Vorteil.

enum:
Was das ist, wurde ja schon geklärt. Aber gibt es die in Java wirklich nicht?!!! Und ja, selbst wenn man hierzu eine eigene Klasse definieren müßte, fände ich den Aufwand trotzdem nicht zu hoch.

class Mobile {
   enum Richtung { nord,
                   nordost,
                   ost,
                   suedost,
                   // usw...
                 };
   void go(Richtung richtung) throw();
};

Was bleibt da noch für die Schnittstellenbeschreibung von go() übrig?! (Ob der Name der Methode gut gewählt ist, müßte sich wohl erst im Kontext klären.)

Stefan.

shoat

DStefan schrieb:

Deshalb gilt für mich die goldene Regel, alles als Code zu schreiben, was man als Code schreiben kann, und Kommentare nur als zweite, nachrangige Instanz für Dokumentation zu sehen. Das gilt natürlich nicht nur für die Beschreibung einer Funktion, sondern auch für den Code innerhalb von Funktionen.

Du hast vollkommem recht, der Code muss so sprechend, als irgendmöglich gestaltet werden. Alle Kommentare innerhalb der Funktion (Klasse) können bestimmt recht kurz gehalten werden.

DStefan schrieb:

Den Unterschied (von shoat) zwischen Usern der Funktion und denen, die sie warten müssen kann ich eigentlich nicht nachvollziehen - jedenfalls nicht in diesem Kontext.

Ich habe dabei von Kommentaren im allgemeine geredet, wenn ich mißverstänlich ausgedrückt habe, dann tut es mir Leid.

Auf jeden Fall möchte ich an der Unterscheidung festhalten. Kommentare an unterschiedlichen Stellen haben verschiedene Zielgruppen, damit müssen auch auch verschieden gestaltet werden. Danke, dass ihr mich darauf aufmerksam gemacht habt! Allerdings muss ich mich verbessern:

DStefan schrieb:

Mir geht es darum Kommentare zugunsten des Codes in den Hintergrund zu rücken. Das ist für alle Entwickler, die damit umgehen müssen von Vorteil.

Soweit hast Du vollkommen recht. Alle Kommentare dürfen auf zugunsten des Codes in den Hintergrund rücken. Wirklich alle! Diese Aussage kann ich wirklich gut akzeptieren. Jedenfalls, solange darunter die Verständlichkeit des Codes für Kenner nicht leidet!

Nur auf eines möchte ich beharren. Schnittstellenbeschreibungen, die nach außen gehen (public!), die also auch der User / Laie verstehen muss, sollten zusätzlich sehr ausführlich, meint newbie-tauglich gehalten werden.

(In der Tat sind, dass auch die Schnittstellen, an denen unter Java javadoc ansetzt, auch, wenn ich es bisher nie so empfunden habe.)

Können wir uns darauf einigen?

Wenn mich jemand davon abbringen will, dann muss er sich schon gute Argumente einfallen lassen!

Viele Grüße und v. a. vielen Dank!

Ciao
shoat

volkard

shoat schrieb:

Du hast wirklich vollkommen recht, dass es die obere Lösung vollkommener Schachsinn ist. Und natürlich ist die untere Lösung viel besser. Aber in der Form kann man sie meiner Meinung nach unmöglich belassen. So würde ich sie idealweise einstellen.
public class Mobile...
    /**
     * Versetzt das Mobile in die angegebene "richtung".
     * @param 	richtung    Gibt die Richtung an. Dabei bedeutet richtung%9 
     *                        gleich 0 linksunten, 1 unten, 2 rechtsunten, 
     *                        3 links, ...
     */

ähm. wolltest du mir jetzt zeigen, daß ein wechsel nach java besser ist? oder daß man mehr kommentare machen soll?

übrigens: ein wort sagt weniger als 1e-3 bilder.

/* richtungen: 012
               345
               678
*/

[quote="shoat"]

public void go (int richtung)
    {
        this.posX += richtung%3-1 ;
        this.posY += richtung/3-1 ;
    }
}

Genau so finde ich es am besten. Damit schneidet die Funktion (denke ich?) auch bei Metriken gut ab und nichts von Deiner guten Lösung geht verloren.[/java]
"am besten" ist eine so fette beschreibung...
nee, offensichlich ist schonmal das hier besser:

/*evtl private:*/
void go(Vector richtung)
{
    pos+=richtung;
}
public:
void go(enum Richtungsname richtungsname)
{
   pos+=richtungsnameToRichtung[richtungsname];
}
//enum und [] nur zur verdeutlichung.

aber am besten ist das noch nicht.

double* find(double toFind,double* arr,int size) 
{ 
   for(int i=0;i<size;++i) 
      if(arr[i]==toFind) 
         return &arr[i]; 
   return 0; 
}
Guter Algorithmus, aber auch zu dieser Funktion (zumindest, wenn sie public ist) gehört meinesachtens eine Schnittstellenbeschreibung!

echt?

Warum? Ganz einfach. Wenn Dritte Deinen Code nutzen sollen, dann fällt ihnen dies viel leichter, wenn die nutzbaren Schnittstellen verständlich beschrieben sind. I. d. R. dauert es viel länger, wenn man erst den Quell-Code anschauen und verstehen muss.

aha. I.d.R. also. aber obige funktion ist doch a.d.R., oder? was ist, wenn man so geil programmiert, daß 95% der funktionen in diesem sinne a.d.R sind? abgesehen davon, daß dann a.d.R d.R ist, wodurch etwas unsinnigerweise i.d.R a.d.R ist, wäre es i.d.R nicht nutwendig, die schnittstelle nochmal extra zu beschreiben. natürlich beschreibt man die 5% a.d.R-Funktionen. also man beschreibt das, was nicht offensichtlich ist. i.d.R kann jeder ein ++x lesen und man schreint nicht "//erhöht x" hin. wozu dir find(...) oder die go(...) noch spezifizieren. oder fine mal einen, der bei "void go(Vector richtung)" oder "void go(enum Richtungsname richtungsname)" nicht sofort weiß, was die methode macht. (falls du ihn findest, leih ihm netterweise ein anfängerbuch.)

shoat schrieb:

Nur auf eines möchte ich beharren. Schnittstellen, die nach außen gehen (public!), die also auch der User / Laie verstehen muss, sollten zusätzlich sehr ausführlich, meint newbie-tauglich gehalten werden.

(In der Tat sind, dass auch die Schnittstellen, an denen unter Java javadoc ansetzt, auch, wenn ich es bisher nie so empfunden habe.)

Können wir uns darauf einigen?

Nein, ich finde das weder notwendig noch wünschenswert!

Code, der Newbie- oder gar Laien-tauglich ist, ist normalerweise alles andere als qualitativ hochwertig! Dasselbe gilt (vielleicht sogar in verstärktem Maße) für Kommentare bzw. Schnittstellenbeschreibungen. Wie soll ich mir Code vorstellen, der dieser Anforderung genügt, was soll ich voraussetzen können und was nicht?! Das ist doch bei diesen Zielgruppen kaum zu entscheiden. Ich müßte so ziemlich alles erklären, was schon im Code zu sehen ist, denn ein Newbie (oder gar ein Laie) kennt es möglicherweise nicht.

Qualitativ hochwertiger Code muß voraussetzen können, daß der Entwickler, der damit zu tun hat, sein Geschäft beherrscht. Das bedeutet nicht nur, daß er die Sprachmittel und Standard-Bibliotheken erschöpfend kennt, sondern auch Dinge, wie Design Patterns, grundlegende Algorithmen usw., die also mit der Programmiersprache nichts zu tun haben. Und selbst Kenntnisse bezüglich des Fachgebiets, für das die Software geschrieben ist, muß man voraussetzen können - zumindest grundlegende Kenntnisse.

Newbies sollten genügend Erfahrungen mit nicht produktivem Code machen, bevor sie ernsthaft zu entwickeln beginnen. Sie haben an produktivem Code nichts zu suchen! Das gilt natürlich erstrecht für Laien. In diesem Sinne ist natürlich wieder einmal XP erwähnenswert: Das Pair Programming ist, finde ich, genau das Richtige, um Newbies schnell an ihren Job heranzuführen. (Bloß schade, daß in diesem unserm Lande die Firmen anscheinend überhaupt kein Intersse an XP haben. Oder weiß jemand einen XP-Job für mich? ).

Stefan.

volkard

DStefan schrieb:

Im Falle von find() fehlt eine Fehlerbehandlung (arr darf nicht 0 sein).

und was passiert da? ein assert? da ist meine schutzverletzung doch gleichwertig.
bei msvc gilt: die dereferenzierung von 0 löst eine feine schutzverletzung aus, die öffnet die ide und zeigt auf die code-zeile, wo es passiert ist und man kann prima die variableninhalte und alles so inspizieren und in wenigen sekunden hat man den fehler behoben.

volkard

Helium schrieb:

assert(ergebnis * ergebnis == radiant);

nutzlos. das ist nur ne umformulierung des programmcodes. wirksamer ist ne testfunktion, die nur den zweck hat, die funktion zu testen.
dann passieren auch so fehler nicht, wie "assert(ergebnis * ergebnis == radiant);" statt "assert(fabs(ergebnis*ergebnis-radiant)<=42*WILLKUER);"