Wie dokumentieren/definieren professionelle Entwickler Projekte?

[captmcneil]

Irgendwie hast Du einen sehr unangenehmen Diskussionsstil.

 

[Cobinja]

Ich würde sagen, dass eine Funktion, wie die von captmcneil als Beispiel gebrachte, keinen großen Kommentar braucht.

Aber ich muss auch sagen, dass es irgendwo eine Frage der Höflichkeit gegenüber anderen Entwicklern ist, seinen Quellcode auch innerhalb von Funktionen zu kommentieren, auch dann, wenn der Quellcode selbsterklärend geschrieben ist. Wenn ich unkommentierten Quellcode lesen muss, fühle ich mich, auf gut deutsch gesagt, verarscht.

 

[roker002]

Hi

@captmcneil
Wie dein Nachredner schon gesagt hat. Wenn du Quellcode Kommentieren mußt weil er sich nicht selbst erschließt dann sollte man darüber nachdenken was man besser machen kann.

und nein ich bin kein SoftwareArchitekt trotzdem programmiere ich schon lange an großen Projekten und daher kann ich aus Erfahrung sprechen.

Wenn der Code so kompliziert ist das man ihn versuchen muß zu erklären dann schafft das eine Erklärung selten es wirklich anständig aufzuklären. Die beste Erklärung ist ein Code der sich selbst erklärt.
Das heißt also wenn die Codevariablen gut benannt wurden, wenn vorher über die Software nachgedacht wurde und das von anfang an anständig durchgezogen wurde so ist eine Documentation über jeder Methode vollkommen ausreichend.

Gruß Maria

Ähm @Maria, wie lange Programmierst du? Nur so aus Neugierde.
Ja das ist das Problem. Wenn du versuchst alle Variable sinnvoll zu benennen dann, hast du bald zu viel Codezeilen.

Kommentare sind sinnvoll für Weiterentwicklung/Verbesserung oder Behebung bestehenden Bugs. Dazu muss ich sagen, dass es nicht dafür gedacht worden ist die Kommentare so zu missbrauchen. Na ja ich tue das auch, weil ich einfach zu faul bin im Buch alles zu führen.

Und von wegen durch die Auswahl der Namen kannst du alles unkommentiert lassen. Ich kann dir einen Beispiel liefern. Eine Abrechnung mit 31 Tagen und max 10 Tabellen soll zusammengefasst werden und die Gesamtsumme aller Leistungen aufgeführt werden. Du hast quasi eine Liste aus 10 Einträgen und eine weitere geschachtelte Liste mit 31 Einträgen. Wenn du da nicht kommentierst, egal wie auch immer die Namenswahl ausfällt, wirst du nach 2 Woche den gesamten Ablauf vergessen.


Goldene Regel bei mir... schwierige abschnitte immer auskommentieren. Am besten malt man sich das auf, wie der Ablauf des Codes stattfinden soll, um später jederzeit sich daran erinnern zu können. Die Ablaufdiagramme zum Klassendiagramm beifügen und irgendwo sicher ablegen.
Bei Mehrdeutigen Methoden sollte man paar Beispiele als Kommentar auch abgeben.

 

[TheCadillacMan]

Ich bin zwar kein IT-Architekt aber ich schreib trotzdem mal meine Meinung.

Ich halte weder "keine Kommentare" als auch "so viel Kommentare wie möglich" für die optimale Lösung.

Grundsätzlich bin ich auch dafür, dass der Code selbsterklärend sein sollte. Das geht aber eben nicht immer. Sei es weil die verwendete API schlecht ist (Stichwort: COM), oder weil der verwendete Algorithmus bzw. Prozess einfach zu komplex ist.

Ich bediene mich mal rooker02s Beispiel.

Das ist unnötig:

// Deaktiviere die Tabellenborders...
innerTable.Borders.Enable = 0;

Hier wiederholt das Kommentar den Code.

Das ist sinnvoll:

// Da es nicht mit 2x2 Tabelle funktionieren will, muss man die zweite Zeile per hand noch einmal hinzufügen.
innerTable.Rows.Add(missing);

Hier erklärt das Kommentar den Code.

Ein absolutes Muss sind für mich nur die Methoden- und Klassenkommentare. D. h.: Was macht die Klasse/Methode. Was sind gültige Parameterwerte etc.

 

[Maria S.]

Wieso ist doch nur eine Frage ..

Hast du dir den link den ich gepostet habe mal durchgelesen .. das ist es was ich meine.

Ich sag ja nicht das Kommentare überhaupt nicht sein sollen. Ich dokumentiere meinen Code auch.

[zitat]
Kommentare sind in der Sprache der Smells zwar ein guter Geruch, werden aber oft wie Deodorant eingesetzt, das einen üblen Geruch überdeckt: Wo ein Kommentar notwendig scheint, ist häufig der Code schlecht". Das beschreibt es sehr gut. Kommentare sind nicht generell falsch. Es gibt Bereiche, die einen Kommentar brauchen.
[/zitat]

Und wenn ich auf Code treffe wo 70% Kommentar ist und 30% Code der so aussieht:

// diese Methode addiert 1 zu 2
public function adz( $a, $b ){
  //hier addiere ich die beiden zahlen
  $c=$a+$b;
  // ich gebe die Zahlen zurück damit man das Ergebnis verwenden kann
  return $c;
}

Schon klar das das jetzt übertrieben ist (hoffe ich), aber guter Code erklärt sich von selbst. Das war meine Aussage vom Anfang.
Klar soll Kommentiert werden, nur Sinnvoll. Und wenn man gut programmiert, fallen zu 99,99% keine inline Kommentare an. Dann reicht es voll und ganz über die Klasse, Eigenschaften und Methoden die PHPDocumentor Kommentare zu schreiben.
Und wenn du eine Optimierung hast, lagerst du diese Funktionalität in eine eigene Klasse oder mindestens Methode aus, die dann wieder einen PHPDocumentorKopf hat. Wenn du das nicht tun würdest hättest du das OOP Gesetz der einzigen Verantwortung verletzt.

Gruß Maria

 

[captmcneil]

Ich würde sagen, dass eine Funktion, wie die von captmcneil als Beispiel gebrachte, keinen großen Kommentar braucht.

Aber ich muss auch sagen, dass es irgendwo eine Frage der Höflichkeit gegenüber anderen Entwicklern ist, seinen Quellcode auch innerhalb von Funktionen zu kommentieren, auch dann, wenn der Quellcode selbsterklärend geschrieben ist. Wenn ich unkommentierten Quellcode lesen muss, fühle ich mich, auf gut deutsch gesagt, verarscht.

Genau darum geht's. Es geht im Team darum, einheitliche Code-Richtlinien zu befolgen. Das gehört einfach zur sauberen Arbeit. Wenn jeder so codiert, wie ers für notwendig hält, mag das zwar alles für sich sinnvoll sein, aber die Resultierende Codesumme ist uneinheitlich und deswegen anstrengend zu lesen für jeden einzelnen. Dazu gehören halt so Regeln wie, man kommentiert jede Funktion. Wenn sowas fehlt, ist das einfach schludrig.

Ganz davon abgesehen bieten anständige IDEs solche Kopf-Kommentare auch als Tooltipps o.ä. an. Nicht jede Funktion, die man Benutzt, will (oder KANN -> Bibliotheken & co!) man sich anschauen. Hier ist man vollständig auf Dokumentierung angewiesen.

Ergänzung (16. August 2010)

@Maria S.
Du sagtest "Kommentare stinken". Du argumentierst hier gerade wie ein Fähnchen im Wind. Erst kamen mit einer Riesen-Polemik (sorry) Aussagen der Art "wer kommentiert, kann nicht Programmieren", und jetzt banalisierst Du die Aussagen anderer Leute mit dem blöden Addier-Funktionsbeispiel. Irgendwie kann ich das nicht ernst nehmen.

 

[Maria S.]

Genau meine Meinung captmcneil.

Kopfkommentare in Klassen, Methoden, Eigenschaften gehören dazu.

Kommentare in einer Funktion gehört da nicht hin.

Um zu erklären was die Funktion macht gibt es KlassenDiagramme und andere Sachen die Ausdrücken was passiert ( UseCase, Anwendungsfalldiagramme, Sequenzdiagramme, Kollaborationsdiagramme, Zustandsdiagramme, Aktivitätsdiagramme, Verteilungsdiagramme und bestimmt noch einiges mehr).

Und wie schon gesagt eine Klasse die mehr als eine Verantwortlichkeit hat ist schlechter OOP Stil.

Und um es mal auf die Spitze zu treiben. Wer sagt er schreibt Kommentare damit man erkären kann das die funktion der Performance dient .. hmm jede Kommentarzeile muß geparst werden und kostet jedesmal beim parsen Zeit. Hust ich weiß das war gemein nicht bös nehmen.

Gruß Maria

PS: Sorry wollte nicht provozieren wollte nur meine Meinung vertreten

Ergänzung (16. August 2010)

Achja roker002 um deine Frage zu beantworten ich programmiere seit 1989.
Angefangen wie wohl fast jeder mit Basic auf dem C16+4, danach Pascal, dann Delphi, dann Ausflüge in Java, FreePascal, C++. Seit Anfang 1998 programmiere ich in PHP.

Hoffe das beantwortet deine Frage

@captmcneil dann lies doch noch mal meinen ersten Post und nicht nur den ersten Satz. Da wird erklärt wie ich es meine und es gilt immer noch .. der link den ich gepostet habe ist nicht umsonst da .

 

[captmcneil]

@Maria S.
Du bist aber immernoch nicht darauf eingegangen, dass man kommentiert, um das "Warum" zu erklären. Das Beispiel von TheCadillacMan finde ich da perfekt.

Es kommt natürlich darauf an, worin man entwickelt. Wenn man Systemprogrammierer ist und in, ich sag mal, maschinennahen Sprachen unterwegs ist, mag das anders sein, aber in moderner Business-Software wimmelt es von solchen Fällen, wo durch den Code absolut klar ist, WAS passiert, aber nicht, warum es passiert.

Es ist mir klar, dass Kommentare nicht das nochmal ausführen sollten, was sowieso im Fachkonzept oder so steht, aber gerade so Sachen wie

// hier ist xyz abseits vom Standard implementiert aus Performance-Gründen

muss man einfach kommentieren! Und sowas gehört auch nicht in den Methodenkommentar. Im Methodenkommentar steht das, was der Benutzer der Methode wissen muss. In der Funktion ist das kommentiert, was der Entwickler wissen muss, der die Methode erweitert oder korrigiert.

Anders gesagt: es gibt viele richtige Wege, eine Sache zu implementieren. Man sollte aber kommentieren, warum man sich für den einen Weg entschieden hat.

 

[Cobinja]

Kommentare in einer Funktion gehört da nicht hin.

Um zu erklären was die Funktion macht gibt es KlassenDiagramme und andere Sachen die Ausdrücken was passiert ( UseCase, Anwendungsfalldiagramme, Sequenzdiagramme, Kollaborationsdiagramme, Zustandsdiagramme, Aktivitätsdiagramme, Verteilungsdiagramme und bestimmt noch einiges mehr).

Dem kann ich nur bedingt zustimmen.

Klar sind Klassendiagramme etc. wichtig. Aber auch diese Diagramme können nicht alles erklären, am wenigsten implementierungsspezifische Dinge. Solche Sachen gehören m.E. immer in die Codekommentierung und dort vor allem dahin, wo der entsprechende Code steht, also als Inline-Kommentare.

 

[ljnk]

Die öffentliche Schnittstelle sollte n Java mit javadoc, in .NET mit den eingebauten XML Kommentaren (Sandcastle) und ansonsten per Doxygen oder ähnlichem Tool erfolgen.

Kommentare sind bis auf wenige ausnahmen (z.B. Performancetweaks) schlechter stil und auch eine Form der Redundanz - wie oft habe ich so etwas gesehen:

int length; // in cm

anstelle von

int lengthInCm;

Worst case ist, wenn der Code ohne den Kommentar gepflegt wurde und so inkonsistenzen auftreten. Diese Bugs sind unglaublich schwer zu finden und können durch den Verzicht von überflüssigen Kommentaren komplett vermieden werden. Hier sagte jemand "lieber zu viel als zu wenig" - das Gegenteil ist richtig. Lieber frage ich einmal mehr beim Kollegen nach als auf veraltete Kommentare im Code hereinzufallen.
Kommentare beschreiben bitte immer WARUM man etwas macht, nie WAS gemacht wird. Ansonsten hilft alles diskutieren nicht, ich denke das Thema ist breit genug in Clean Code erläutert. Zur doku von öffentlichen Schnittstellen sollte man sich die passenden Kapitel in Effective Java ansehen, dann klappts auch mit den Kollegen.

@cptnmcneil
"Kopfkommentare" sind teil der öffentlichen API und haben nichts, aber auch gar nichts mit gewöhnlichen Kommentaren ala // +0.5 um richtig zu runden zu tun.
Inline-Kommentare (und übrigens auch Magic Numbers) können zu 95% in Variablennamen konvertiert oder durch extrahieren von wenigen Codezeilen (double roundUp(double value, double stepSize)) in eine neue Methode vermieden werden. Gut gepflegte API-Beschreibungen dagegen sind unerlässlich.

@roker

Ja das ist das Problem. Wenn du versuchst alle Variable sinnvoll zu benennen dann, hast du bald zu viel Codezeilen.

Da kommt mir das essen fast wieder hoch.. LOCs oder LLOCs sind keine sinnvolle Maßeinheit für die Komplexität deines Codes. Sicher sollten variablennamen nicht länger als 20 oder 30 Zeichen sein, aber aus Tippfaulheit oder angst vor zu vielen LOCs keine sprechenden Variablennamen zu benutzen ist einfach nur dumm. Es ist so einfach.. Variable für den Threadpool um den Stack abzuarbeiten heißt tp und ist angenehm zu tippen. Sobald mein Test grün wird und es ans Refactoring geht wird ein tp markiert, Strg+R, Strg+R: tp wird umbenannt nach openJobsInStackQueue oder was auch immer und alle sind zufrieden. Wer das nicht schafft wird nie ein halbwegs anständiger Softwareentwickler.

 

[Maria S.]

@captmcneil
Du sagst
Und sowas gehört auch nicht in den Methodenkommentar. Im Methodenkommentar steht das, was der Benutzer der Methode wissen muss.

Und genau da wiedersprech ich dir. Wenn in der Methode etwas anders gemacht wird als im Methodenkopf in der Erklärung steht dann hast du einen grund dieses zu abstrahieren es in eine eigene Methode oder Klasse zu kapseln und die Beschreibung gehört dann wieder ganz normal in den Kopf der Methode (Klasse) am besten mit phpdocumentor Code.

Das wäre sauberes Programmieren.


@Cobinja
Aber auch diese Diagramme können nicht alles erklären, am wenigsten implementierungsspezifische Dinge. Solche Sachen gehören m.E. immer in die Codekommentierung und dort vor allem dahin, wo der entsprechende Code steht, also als Inline-Kommentare.

Also bei euch hört sich das immer an als wenn ihr Methoden habt die kilometer lang sind. Ich schreibe selten Methoden über 20 Zeilen. Mein Schnitt pro Methode dürfte so bei 5-6 Zeilen liegen. Und die sind selbst beschreibend anhand des Namens und der weiteren Methoden/Klassen die dort aufgerufen werden.

Nicht bös nehmen aber ich glaube das das so sein sollte.

Wenn ich mir manche PEAR Klassen angucke wo fast alles nur Kommentare sind .. dann muß ich immer den Kopf schütteln.

Ach und ich arbeite auch in einem nicht ganz so kleinem Team als Technische Leiterin und entweder haben die Leute Angst vor mir und sagen es mir nicht das sie meinen Code nicht lesen können oder aber sie kommen damit zurecht

Gruß Maria S.

PS_ Danke ljnk

 

[Erdmännchen]

Um die Diskussion hier nicht über Kommentare ausarten zu lassen, aber weil ich meinen eigenen Standpunk noch kurz nennen will:
Ich sehe es genauso wie Maria S.
Code muss man ohne Kommentare lesen können wie ein Buch, er erklärt sich selbst. Das ist guter Code, das ist schöner Code.
So Argumente, "ja aber da wird doch mein Code drei mal so lang, wenn ich die Kommentare weglass und statt dessen anders benenne..." ... falsch, du lässt ja sogar Zeilen Weg ;-) Du brauchst vielleicht dreimal so lang, um deine Methoden "besser" zu benennen, aber danach weiß man einfach schon durch einen Blick auf die Signatur der Methode, was sie macht, warum sie es macht und was dahinter passiert.

BTW: Von "Refactoring" habt ihr Leute dann auch noch nichts gehört oder?

So, um das ganze mal mit einem Lehrbuch zu belegen, holt euch mal das Buch "Clean Code" von Robert C.Martin und lest es...Ist einfach geschrieben und meiner Meinung ( und auch alle die ich kenne, die es gelesen haben) eines der besten, um seinen Programmierstil zu verbessern, wenn man lernwillig ist...
(Ich bin nicht verwandt oder verschwägert und ziehe auch keinen anderweitigen Vorteil aus diesem Literaturhinweis, möchte nur ein sehr gutes Buch empfehlen)

So jetzt aber zurück zum Thema dieses Threads:
Softwareprojekte brauchen Dokumentation. Ist klar, wurden hier auch schon verschiedene Werkzeuge genannt. Was man aber meiner Meinung nach aufpassen sollte, man sollte z.b. die Dokumentation nicht mit einem sog. Pflichtenheft oder Anforderungskatalog verwechseln. Denn das sind zwei verschiedene Dinge:
In den Anforderungen steht, wofür der Kunde bezahlt und was umgesetzt werden soll. In der Dokumentation steht, was dein Produkt macht. Also alles, was man wissen muss, um es korrekt und seinem Sinn entsprechend zu benutzen.

 

[ljnk]

Anstatt groß zu weiter zu quaken geb ich jetzt einfach mal ein Beispiel, wie man es macht. Die Methode FormatTable könnte man locker noch weiter Aufbrechen, als Proof-Of-Concept soll das aber mal durchgehen.

So hat man es früher gemacht und es ging schief:

/// <summary>
/// Schreibt eine 2x2 Tabelle in der Zelle Adresse
/// </summary>
/// <param name="Adresse">Tabellenzelle, in der die innere Tabelle erstellt wird.</param>
private void Info(Cell Adresse)
{
    ///Erstelle die innere Tabelle in der Zelle 2x2
    Table innerTable = Adresse.Tables.Add(Adresse.Range, 1, 2, WdDefaultTableBehavior.wdWord9TableBehavior, missing);

    ///Da es nicht mit 2x2 Tabelle funktionieren will, muss man die zweite Zeile per hand noch einmal hinzufügen.
    innerTable.Rows.Add(missing);

    Cell c11 = innerTable.Cell(1, 1);
    Cell c12 = innerTable.Cell(1, 2);
    Cell c21 = innerTable.Cell(2, 1);
    Cell c22 = innerTable.Cell(2, 2);

            
    ///Ändere die Schrift
    c11.Range.Font.Size = 8;

    this.SetCell(c11, Kunde.ToString(), WdParagraphAlignment.wdAlignParagraphLeft);
    c11.VerticalAlignment = WdCellVerticalAlignment.wdCellAlignVerticalCenter;
    ///Ändere Tabellelänge auf 70%, da sonst Design einfach hässlich ist.
    c11.PreferredWidthType = WdPreferredWidthType.wdPreferredWidthPercent;
    c11.PreferredWidth = 70;
            
    this.SetCell(c12, Kasse.ToString(), WdParagraphAlignment.wdAlignParagraphLeft);


    c21.Range.Font.Size = 12;
    this.SetCell(c21, Kasse.ToString(Systems.Kassen.Info.Adresse), WdParagraphAlignment.wdAlignParagraphLeft);
            
    c22.Range.Text = string.Empty;

    innerTable.PreferredWidthType = WdPreferredWidthType.wdPreferredWidthPercent;
    innerTable.PreferredWidth = 100;

    ///Deaktiviere die Tabellenborders...
    innerTable.Borders.Enable = 0;
}

Wenn man einmal die Kommentare sieht, versteht man sofort alles.

So macht man es mit ein wenig Erfahrung:

    public void WriteInfoCellsInCell(Cell adresse)
    {
        Table innerTable = CreateInnerTable(adresse);
        formatAddressTable(innerTable);
    }


    private Table CreateInnerTable(Cell adresse)
    {
        Table t = Adresse.Tables.Add(Adresse.Range, 1, 2, WdDefaultTableBehavior.wdWord9TableBehavior, missing);
        //HACK: Da es nicht mit 2x2 Tabelle funktionieren will, muss man die zweite Zeile per hand noch einmal hinzufügen.
        // Dieser Kommentar ist sinnvoll, da Bug oder sonstiger Hack
        t.Rows.Add(missing);
        return t;
    }

    private void FormatAddressTable(Table table)
    {
        // schöner wäre hier
        // FormatFont(Table table); FormatBorder(Table table); SetSize(Table table); 
        // oder ähnliches, allerdings habe ich die Idee wohl schon gezeigt
        Cell c11 = table.Cell(1, 1);
        Cell c12 = table.Cell(1, 2);
        Cell c21 = table.Cell(2, 1);
        Cell c22 = table.Cell(2, 2);

        c11.Range.Font.Size = 8;

        this.SetCell(c11, Kunde.ToString(), WdParagraphAlignment.wdAlignParagraphLeft);
        c11.VerticalAlignment = WdCellVerticalAlignment.wdCellAlignVerticalCenter;
        c11.PreferredWidthType = WdPreferredWidthType.wdPreferredWidthPercent;
        c11.PreferredWidth = 70;

        this.SetCell(c12, Kasse.ToString(), WdParagraphAlignment.wdAlignParagraphLeft);


        c21.Range.Font.Size = 12;
        this.SetCell(c21, Kasse.ToString(Systems.Kassen.Info.Adresse), WdParagraphAlignment.wdAlignParagraphLeft);

        c22.Range.Text = string.Empty;

        table.PreferredWidthType = WdPreferredWidthType.wdPreferredWidthPercent;
        table.PreferredWidth = 100;

        table.Borders.Enable = 0;
    }

Rokers Beispiel ist definitiv nichts, was man sich als Beispiel nehmen sollte.

Ps: Falsches Forum für solche Fragen. Ich bezweifle zwar nicht, dass hier fähige Entwickler unterwegs sind, allerdings glaube ich dass du auf stackoverflow oder ähnlichem wesentlich besser aufgehoben bist. Am besten die ersten Monate nur mitlesen und Klappe halten, ansonsten zerreißt man dich recht schnell in der Luft. Lerneffekt ist aber immens.

 

[roker002]

Das ist unnötig:

// Deaktiviere die Tabellenborders...
innerTable.Borders.Enable = 0;

Hier wiederholt das Kommentar den Code.

Ich würde nicht sagen dass es unnötig ist. In der API Beschreibung steht dass Enable einen Boolean Typ besitzt. Hier in der Bibliothek ist es aber ein INT.

Und ja, dieser Beispiel habe ich reingestellt, obwohl ich noch nicht mit der Optimierung fertig war. Wenn man auf eine schnelle Hand macht, dann vernachlässigt einiges. Ich glaube es gibt kaum Leute die 100% alles beim ersten mal korrekt machen. Wieso sonst ist die Software meist fehlerhaft und muss mit 20 Patches nachgebessert werden.

Habe jetzt die nachfolgende Beiträge nicht gelesen, aber ihr müsst euch selbst beurteilen können bevor ihr über anderen richtet. Ich habe hier auch keinen irgendwie beleidigt. Also bitte lasst das mit klugscheißern. Herrgottbeschreißerle gibt es ja schon seit länger als dieser Thread

Obwohl die Metadaten bei MS Word API auskommentiert ist, finde ich trotzdem das ganze für sehr verwirrend.

@Topic
@CPU
Kommentiere das aus was für dich wichtig ist, damit du später dich schneller einarbeiten kannst. Und ja, noch eine goldene Regel... verschiebe nie die Kommentierung auf später. Ich kann dir sagen, dass du 100% das nicht nachholen kannst. Und später kannst du dich vielleicht nicht mehr an den Code erinnern was genau gemacht wird.

 

[Maria S.]

Moin moin

@roker002

// Deaktiviere die Tabellenborders...
innerTable.Borders.Enable = 0;

Ich würde nicht sagen dass es unnötig ist. In der API Beschreibung steht dass Enable einen Boolean Typ besitzt. Hier in der Bibliothek ist es aber ein INT.

Das mein ich. Wenn dort wirklich ein INT verlangt würde wäre die Bezeichnung falsch. Denn Enable erwartet eindeutig einen Boolschen Wert.

Bei mir in der Firma wäre es so das, wenn Enable hier wirklich einen INT verlangt es dafür in den Code Richtlinien eine Richtlinie dafür gibt die da aussagen würde:

Enable kann true, 1, on oder false, 0, off sein, und dann würde es eine Methode geben die das automatisch in das richtige Format konvertiert.
Heißt also wenn Enable = off geschrieben wird, nimmt diese Methode diesen wert und wandelt sie in ein false um und mit dem Wert kann dann überall gearbeitet werden.

Mal abgesehen davon, würde ich jedem meiner Programmierer die Leviten lesen wenn sie so etwas machen würden. Boolean ist Boolean und da haben Zahlen nichts zu suchen.

Wobei ich die Einschränkung machen muß das ich nur für PHP spreche, alle anderen Sprachen hab ich zu lange nicht mehr benutzt um da wirklich eine Aussage treffen zu können.

Und was Fremde Apis angeht die so etwas benötigen. Da schreib ich mir doch glatt eine Dekorator oder FacadeKlasse für, die dann genau dieses Problem beschreibt und für mich löst. Und genau dann gehört das wieder in den jeweiligen MethodenKopf als PHPDocumentor.

Gruß Maria

 

[DonnyDepp]

wer von euch programmiert überhaupt bei einem unternehmen in größeren projekten für richtige kunden?

was mir bisher für code unter die finger geraten ist, ist alles ungenügend bis gar nicht kommentiert, die logausgaben nichtsaussagend (nur so nachm motto "an dieser stelle im code komm ich vorbei") und workarounds en masse, die vieles "doppelt programmiert" aussehen lassen.
und das ist in jedem projekt so, was über mehr als 3 jahre entwicklungszeit hatte und paar jahre in der wartung ist.

man kann das zeug so gut kommentieren wie man will, später ändern sich die anforderungen und man muss den bestehenden code anpassen. damit werden viele kommentare ungültig oder falsch.

was sinnvoll ist, ist ein gut organisiertes wiki. da kann jeder entwickler seine gedanken und notizen zu seinen modulen oder codeänderungen reinschreiben.
dort lassen sich dann auch stellen ändern, ohne im quellcode herumzupfuschen, alles neu einchecken bzw. infolge dessen neu kompilieren zu müssen.


für so kleine 2-3mann miniprojekte kann man total easy ne gute dokumentation und modellierung führen.
aber ob das dann immer noch den aufwand rechtfertigt, ist wieder eine andere frage.
das sind dann wahrscheinlich eh "nur" paar hundert klassen, durch die man sich auch ohne doku durcharbeiten kann.

ausserdem zahlt der kunde fürs endprodukt und dessen wartung und nicht für die dokumentation des quellcodes.
wenn man dem zuviele arbeitstage für modellierung und dokumentation in rechnung stellt, wird er auf jeden fall meckern.

private Table CreateInnerTable(Cell adresse)
{
return Adresse.Tables.Add(Adresse.Range, 1, 2, WdDefaultTableBehavior.wdWord9TableBehavior, missing);
//HACK: Da es nicht mit 2x2 Tabelle funktionieren will, muss man die zweite Zeile per hand noch einmal hinzufügen.
// Dieser Kommentar ist sinnvoll, da Bug oder sonstiger Hack
innerTable.Rows.Add(missing);
}

ljnk, soll die anweisung "innerTable.Rows.Add(missing);" nach dem return stehen?
da kommter doch gar nicht mehr lang

typischer copypaste fehler, was?

 

[kuddlmuddl]

Ich würd gern mal erleben, wie die "Kommentare im Code sind unnütz" Fraktion Assembler oder C Code modifiziert, der keine Kommentare zwischen den Zeilen hat... Macht sicher viel Spaß
Vor allem, wenn es um was mathematisch anspruchsvolles geht, was man nicht 100% durchdringen will (zeitmangel) aber von einer zuverlässigen Quelle aus die Formeln in Code umwandelt..

Es geht doch im wesentlichen immer um Zeit+Geld
Wird etwas komplizierteres/fummeligeres programmiert, was jemand nochmal lesen muss, zB weil evtl. noch Fehler drin stecken oder weil Schnittstellen/Signaturen verändert werden, freut sich jeder Entwickler, der solchen Code verändern muss, wenn der vorige Entwickler die kryptischen Passagen erklärt...

Die Frage ist dann nämlich: Was dauert länger (=> kostet mehr)
1) Einen Kommentar hinschreiben
oder
2) Im Nachhinein sich in undokumentierten, fremden, komplizierten und evtl. schlechten Code reinzulesen

Kommt halt drauf an. return a+b; darf man natürlich nicht kommentieren, weil lesen+verstehen schnell geht UND weil zu viele Kommentare natürlich auch stören.

Gibt aber auch kompliziertere Dinge...

Maria S.:
Mal abgesehen davon, würde ich jedem meiner Programmierer die Leviten lesen wenn sie so etwas machen würden. Boolean ist Boolean und da haben Zahlen nichts zu suchen.

Nicht alle verbreiteten Sprachen kennen überhaupt den Typ bool....
ein

if (isFolder(path)) {
    // ...
}

ist in C nicht gerade unüblich? Auch wenn isFolder() einen int returned...
Das war nicht als Angriff gegen dich gemeint. Wie ich am Anfang schon angedeutet habe.. es kommt auch auf die verwendete Sprache an, ob Kommentare nötig sind und auch darauf, WAS eigentlich programmiert wird.
Nen Stringparser versteh ich auch unkommentiert.. aber irgendwelche superkrassen mathematischen Optimierungsverfahren die auch noch stark Laufzeitoptimiert sind würde ich nicht unkommentiert lesen wollen

 

[Maria S.]

Hi kuddlmuddl

Ich würd gern mal erleben, wie die "Kommentare im Code sind unnütz" Fraktion Assembler oder C Code modifiziert, der keine Kommentare zwischen den Zeilen hat... Macht sicher viel Spaß

Na ich bin davon ausgegangen das wir hier nicht über Programmiersprachen der 1., 2. oder 3. Generation reden sondern über mindestens 4. Generation bzw Objektorientierte Generation.

Wird etwas komplizierteres/fummeligeres programmiert, was jemand nochmal lesen muss, zB weil evtl. noch Fehler drin stecken oder weil Schnittstellen/Signaturen verändert werden, freut sich jeder Entwickler, der solchen Code verändern muss, wenn der vorige Entwickler die kryptischen Passagen erklärt...

Meine Meinung dazu hab ich ja schon gesagt, wenn jemand OOP programmiert und etwas in einer Methode/Klasse macht was er nicht im Methoden bzw. Klassenkopf erklären kann. Dann hat er etwas falsch gemacht.

Im Nachhinein sich in undokumentierten, fremden, komplizierten und evtl. schlechten Code reinzulesen

Genau den gilt es zu vermeiden.

ist in C nicht gerade unüblich? Auch wenn isFolder() einen int returned..

Wie schon gesagt dafür gibt es dann Style und Codevorlagen in jeder Firma die genau so etwas abhandeln.
Und wie gesagt ich spreche halt von den Projekten die ich so mache und die sind halt in den letzten 12 Jahren meistens in PHP.

Das war nicht als Angriff gegen dich gemeint

Hab ich auch nicht so verstanden. Wir diskutieren und das find ich gut ..

Gruß Maria

 

[ljnk]

@donnydepp
auf jeden fall c&p fehler, das passiert wenn man in der forensoftware code refactored. jede modernen IDE hätte an der stelle gewarnt.

Jeder, der hier Standardwerke wie Clean Code, Effective XYZ oder Refactoring to patterns noch nicht gelesen und/oder keine ahnung von TDD und agiler SE hat, soll das bitte nachholen. Wenn man danach noch gute Gründe hat diesen Best Practices zu widersprechen, ist eine Diskussion sinnvoll und angebracht.

Kommentare stören den Flow des Lesers und sollten vermieden werden. Guter Code braucht keine Kommentare. Guter Code sollte das Ziel jedes Entwicklers sein. Hat man keinen guten Code, sollte man Refactoring betreiben, bis man mit dem Ergebnis zufrieden ist. Kommentare sind immer ein eindeutiges Zeichen, dass der Code unverständlich ist. Zu 95% lassen sich diese durch extrahieren in Methoden oder sprechende Variablennamen ersetzen. Techniken hierfür lassen sich in Clean Code erlernen.

//Edit: Natürlich wird hier von einer modernen, funktionalen oder objektorientierten Sprache ausgegangen. Sollte jemand mit Sprachen arbeiten, in denen die ungarische Notation noch Standard ist, dann hat dieser genug Probleme auch wenn er sich nicht um guten Stil schert.

 

[kuddlmuddl]

Sorry, aber da muss ich euch echt nochmal Widersprechen.
Ihr könnt nicht pauschal sagen, dass in allen modernen Sprachen Kommentare IM CODE immer an der falschen Stelle sind und nur von unfähigen Entwicklern gemacht werden, weil fähige Entwickler sofort lesbaren Code schreiben.

Stellt euch vor jemand braucht in einer komplizierten Berechnung ein wichtiges, lange ausgebrütetes Zwischenergebnis wie ne Ableitung einer mehrdimensionalen Funktion oder so.
Ich finde die einzelnen Schritte und Zwischenergebnisse können dann durchaus Stück für Stück als Kommentar in der Funktion stehen. Evtl sogar mit Links auf die jeweils wichtige mathematische Gesetzmäßigkeit.
Wo soll sowas eurer Meinung nach sonst hin? Über die Funktion, wo dann durch javadoc/doxygen jeder nachliest, was die Funktion macht? Wohl kaum. Das "wie" gehört da nicht hin, nur das "was".
In ein externen Dokument? Nen eingescannten Handschriftlichen Zettel? Dann schreib ich ja alles nochmal ab. Und was, wenn ich nur da beim Abschreiben nen Fehler mache? Und wenn jemand zum Bugfix das externe Dokument auf Fehler prüft und keinen findet? Dann muss er ja immer den Zusammenhang zwischen Code und Zettel herstellen. Finde ich auch nicht gut..
Den Code copy&paste in ein neues Dokument und das dann nur dort mit Kommentaren versehen? Was, wenn ich was im echten Code verändern muss und es in der Doku vergesse.. sowas kommt nicht in Frage.

Ich würde dann tatsächlich "viel" Kommentar im Code schreiben und da drunter reduziert den entscheidenen mathematischen Ausdruck für eins der nötigen Zwischenergebnisse.
Weil wenn ich da nen Fehler gemacht habe und den wer anderes suchen muss, sagt der bestimmt nicht:
"Gut dass keine Kommentare da sind. Sowas erklärt sich ja von selbst!"
OOP rettet garnichts imho, wenn sich "kompliziert" (z.B. mathematisch) einfach nicht vermeiden lässt

Außerdem: Was, wenn man ein realistisches Team hat in dem eben viele nicht super Erfahren sind, immer toll lesbaren Code schreiben und auch nebenbei ihren Doktor in Mathe und Informatik gemacht haben? Solche Leute (Praktikanten? Studi Aushilfen? Azubis?) müssen evtl. auch an der Softwareentwicklung beteilgt werden, um Termine einzuhalten oder Kosten niedrig zu halten und da ist es dann allein schon deswegen nötig "mehr" zu Kommentieren, damit jeder es halbwegs nachvollziehen kann.

Die Softwareentwicklungsspezis / Consulting Leute an der Uni haben immer vom Tuck-Faktor geredet. Ein Projekt darf nicht den Bach runtergehen, nur weil plötzlich ein wichtiger Mensch ausfällt (überfahren wird), der als einziger den entscheidenen Mathe-kram versteht. Sowas muss zumindest ansatzweise nachvollziehbar kommentiert sein, damit sich jemand anderes da reindenken kann.

Ich versteh auch das Problem nicht so richtig. Wenn ich mehrere Tage was kompliziertes programmiert habe kostet es mich nur sehr wenige Minuten nebenbei schon ein paar sinnvolle Hinweise in natürlicher Sprache zu ergänzen. Manchmal wird mir dadurch überhaupt erst ein Denkfehler bewusst. Wieviel Zeit ich brauche, wenn ich mich ohne Kommentare nochmal Reindenken muss steht in keinem Verhältnis zu der Zeit die es kostet direkt beim Programmieren zu Kommentieren.