it-swarm-eu.dev

Ist das Schreiben von Kommentaren in Methoden keine gute Praxis?

Ein Freund sagte mir, dass das Schreiben von Kommentaren in Methoden nicht gut ist. Er sagte, dass wir Kommentare nur für die Methodendefinitionen (Javadocs) haben sollten, aber nicht innerhalb des Methodenkörpers. Es scheint, dass er in einem Buch gelesen hat, dass Kommentare im Code bedeuten, dass es ein Problem im Code gibt. Ich verstehe seine Argumentation nicht ganz. Ich denke, das Schreiben von Kommentaren innerhalb des Methodenkörpers ist gut und hilft anderen Entwicklern, ihn besser und schneller zu verstehen. Bitte geben Sie Ihre Kommentare.

63
Srini Kandula

Ihr Freund liegt falsch und nur sehr wenige Programmierer würden ihm zustimmen. Sie sollten Kommentare schreiben, wann und wo immer Sie der Meinung sind, dass sie das Verständnis am besten unterstützen.

151
mqp

Ignoriere deinen Freund. Kommentar nach Bedarf. Aber bemühen Sie sich, Ihren Code selbsterklärend zu machen, damit Kommentare nicht benötigt werden. Denken Sie daran, dass Ihr Computer keine Kommentare ausführt. Daher können Kommentare leicht nicht mehr mit den tatsächlichen Vorgängen synchronisiert werden.

Ich neige dazu, einen Kommentarblock zu verwenden, um ein besonders kniffliges Stück Logik zu erklären, dessen Lesen sonst ein wenig Gehirnarbeit erfordern würde. Und dann werde ich versuchen, die Logik klarer zu machen und die Notwendigkeit einer Erklärung zu beseitigen.

90

Guter Code ist selbstdokumentierend. Eine Methode sollte genau eines tun, und dieses eine sollte anhand des Methodennamens und der Kommentarspezifikationen offensichtlich sein. Das Erfordernis von Kommentaren in der Methode zur Erläuterung der Logik legt daher nahe, dass die Methode in Methoden mit Einzelverantwortung unterteilt werden sollte.

Nun zur Realität. Sie sind mit einer komplexen Spaghetti-Code-Codebasis konfrontiert und versuchen, den Betreuern gegenüber nett zu sein. Sie haben weder die Zeit noch das Mandat, 8 Millionen Codezeilen umzugestalten, und selbst wenn Sie dies tun würden, würde es Nuancen geben, da alles komplex ist. Wie geht's?

44
Mark Peters

Ich bin überrascht, wie viele Menschen dieser Ansicht nicht zustimmen.

  1. Guter Code sollte sich selbst dokumentieren, daher sollten Sie Methodennamen, Variablennamen usw. Sorgfältig auswählen
  2. Ihre Methode sollte nicht so lang sein, dass Sie nicht die gesamte Methode und die Kommentare auf einem Bildschirm sehen können

Es gibt jedoch Ausnahmen. Aber sie sind Ausnahmen. Und der Punkt mit Ausnahmen ist, dass es nur wenige sind. Sie müssen Code wirklich nur inline erklären, wenn Sie etwas tun, das nicht intuitiv ist.

Eine typische Situation, in der Sie möglicherweise Kommentare in Ihrer Methode benötigen, ist, wenn Sie einen lokalen Hack anwenden, um die Geschwindigkeit zu optimieren, der jedoch beim ersten Lesen einem anderen Programmierer einen WTF-Moment geben kann. Das ist ein guter Punkt, um einen Kommentar hinzuzufügen.

Aber im Allgemeinen: Nein, fügen Sie Ihren Methoden keine Kommentare hinzu.

24
markijbema

Ich denke, er spricht über einen Fall wie diesen:

public void upload() {
    // destination Host
    String Host = ....
}

Wo Sie den Code verbessern könnten, indem Sie einen expliziteren Variablennamen anstelle des Kommentars verwenden:

public void upload() {
    String destinationHost = ....
}
18
Douglas

Ich glaube, Ihr Freund bezieht sich auf "Clean Code" von Robert C. Martin. Ich denke jedoch, dass er die Situation ein wenig vereinfacht. Das Buch spricht davon, Methoden klare und beschreibende Namen zu geben, die wir alle kennen sollten, die aber nie genug wiederholt werden können. Das Buch empfiehlt außerdem, Methoden sehr klein zu machen, indem jeder Codeblock, dem ein klarer und beschreibender Name zugewiesen werden kann, in eine eigene Methode eingeschlossen wird. Wenn Sie also der Meinung sind, dass ein Codeblock einen Kommentar benötigt, der erklärt, was er tut, sollten Sie ihn zu einer separaten Methode mit einem geeigneten Namen machen. Wenn alle Ihre Methoden unter 5 Zeilen stehen und alle gute beschreibende Namen haben, sollte theoretisch klar sein, was sie tun, ohne dies in einem Kommentar erklären zu müssen.

Dies bedeutet jedoch nicht, dass Sie niemals Kommentare in Ihren Methoden haben sollten. Der Punkt ist, dass Kommentare nicht redundant sein sollten. Sie sollten Informationen hinzufügen. Wenn Sie eine Methode haben, die genau eines tut und deren Name aus dem Namen hervorgeht, brauchen Sie keinen Kommentar, der erklärt, was sie tut. Es ist jedoch durchaus sinnvoll, einen Kommentar zu haben, in dem erklärt wird, warum es seine Sache auf diese besondere Weise tut. Möglicherweise möchten Sie einen Kommentar, in dem erläutert wird, warum Sie einen Algorithmus einem anderen vorgezogen haben oder warum Sie eine Datenstruktur einer anderen vorgezogen haben. Mit anderen Worten, Sie möchten, dass der Code selbst erklärt, wie er funktioniert, und dass die Kommentare die Gründe für Ihre Entwurfsentscheidungen erläutern, d. H. e. warum die Dinge so gemacht werden.

Das Buch empfiehlt, fehlerhaften Code umzugestalten, anstatt ihn zu kommentieren. Theoretisch ist dies sicherlich eine großartige Idee, aber in Wirklichkeit verfügen Sie möglicherweise nicht über die Zeit oder die Infrastruktur, z. B. ein funktionierendes Unit-Test-Framework mit den entsprechenden Unit-Tests, um dies zu tun. Es gibt Zeiten, in denen Sie mit einer chaotischen Codebasis konfrontiert sind, die Sie gestern zum Arbeiten benötigen. Der einzige Weg, um voranzukommen, besteht darin, zu versuchen, die chaotischen Teile zu verstehen und sie zu kommentieren, um sich Notizen zu machen.

16
Dima

Ja, Sie schreiben definitiv Kommentare in Methoden in Java.

As Suns Code-Konvention sagt:

Java-Programme können zwei Arten von Kommentaren enthalten: Implementierungskommentare und Dokumentationskommentare. Implementierungskommentare sind die in C++ gefundenen, die durch /*...*/ Und // Getrennt sind. Dokumentationskommentare (als "Dokumentkommentare" bezeichnet) sind nur in Java verfügbar und werden durch /**...*/ Begrenzt. Dokumentkommentare können mit dem Javadoc-Tool in HTML-Dateien extrahiert werden.

Die Kommentare in den Methoden sind also Implementierungskommentare.

8
zengr

Ich stimme Ihrem Freund überhaupt nicht zu und behaupte, dass Inline-Funktionskommentare ein sehr wichtiger Bestandteil beim Schreiben von gutem Code sind. Funktionskommentare sollen den Clients des Codes ein besseres Verständnis dafür vermitteln, was der Code tun soll - was seine Parameter und Rückgabewerte bedeuten, welche Arten von Invarianten er beim Ein- und Ausstieg erwartet usw. Inline-Kommentare jedoch richten sich in erster Linie an Betreuer des Codes und idealerweise als eine Reihe von mentalen Notizen für den ursprünglichen Autor des Codes. Sie ermöglichen es, eine komplexe Methode zu betrachten, die eine andere Person gelesen hat, und zu verstehen, was der ursprüngliche Autor dachte. Sie erleichtern auch die Diagnose von Fehlern, da es viel einfacher sein kann, herauszufinden, wie fehlerhaft ein Code ist, wenn eine Fehlfunktion erkannt wird, wenn in den Kommentaren die Absicht des Codes und die getroffenen Annahmen beschrieben werden.

Ich persönlich finde Inline-Kommentare nützlich, weil sie mich zwingen, mir selbst zu beweisen, dass der Code, den ich schreiben werde, korrekt funktioniert. Oft mache ich es mir zur Gewohnheit, keinen Code zu schreiben, ohne vorher klar zu kommentieren, was die Absicht ist und wie es funktionieren wird. Mehr als einmal verhindert dies, dass ich dumme Fehler im Code mache, weil ich feststellen werde, dass meine Erklärung falsch ist oder einen Edge-Fall nicht berücksichtigt.

Natürlich hat jeder seine eigene Codierungsdisziplin, und vielleicht fällt es einigen Leuten leichter, Code ohne Inline-Kommentare zu schreiben und stattdessen den Code in mehrere kleinere Methoden aufzuteilen. Aus Erfahrung habe ich jedoch festgestellt, dass Inline-Kommentare während der Entwicklung und des Debuggens von unschätzbarem Wert sind und für andere Personen, die meinen Code lange nach dem Wechsel zu einem anderen Projekt überprüfen und pflegen müssen, äußerst nützlich sind.

6
templatetypedef

Ihr Freund drückt möglicherweise die Vorstellung aus, dass Kommentare, wenn nicht selbst, ein "Code-Geruch", ein " Deodorant " sind. Dies ist nicht spezifisch für methodeninterne Kommentare, kann jedoch eher für methodeninterne Kommentare als für Präambelkommentare gelten.

Wenn Sie einen Kommentar schreiben, ist dies normalerweise eine Erklärung. Wenn etwas erklärt werden muss - nun, es ist nicht selbsterklärend. Großartiger Code ist selbsterklärend. Wenn Sie also Kommentare hinzufügen, vertuschen Sie das Versagen, sich selbst zu erklären, ohne es selbsterklärend zu machen. Jedes Mal, wenn Sie einen solchen Kommentar schreiben, ändert anstelle von den Code - durch Umbenennen, durch Methodenextraktion usw. - in mach es selbsterklärend, du bleibst hinter dem Ideal zurück.

Aber wir alle verfehlen hin und wieder die Perfektion. Und es ist oft besser, einen erklärenden Kommentar hinzuzufügen, als schwer verständlichen Code ohne Papiere zu lassen.

6
Carl Manaster

Gute Kommentare erklären das Warum nicht das Wie. Das ist hier der Hauptunterschied. Die meisten Leute werden in der Lage sein zu verfolgen, was Sie tun, aber warum Sie es getan haben, erfordert zusätzliche Kommentare. Diese Kommentare sollten so nah wie möglich an der Operation sein.

3
Bill Leeper

Wenn Sie Ihren Code (oder den wirklich schlecht dokumentierten Code einer anderen Person) kommentieren, werden Sie häufig mit Gefühlen von purem Ekel, Hass oder konfrontiert Zorn. Der Code verhält sich möglicherweise frustrierend und unerwartet, und Sie müssen möglicherweise einige sehr böse Hacks hinzufügen, damit er für eine bestimmte Frist funktioniert.

In all diesen Fällen ist es gängige Praxis, Ihre Gefühle auszudrücken, indem Sie die jeweiligen Teile des Codes mit einigen schweren Schimpfwörtern versehen (siehe Linux-Kernel-Fickzählung ). Diese Kommentare müssen in den Methoden enthalten sein, damit sie nicht in der automatisch dokumentierten API angezeigt werden. Weder Ihr Chef noch Ihre Kunden oder andere quellcodeunabhängige Personen werden sie jemals sehen.

Ihre Programmierkollegen werden sich jedoch großartig fühlen Erleichterung und Glück, wenn Sie die Quelle studieren. (Und natürlich können Sie sich Notizen hinzufügen oder den Quellcode in gewissem Umfang als Kommunikationsmedium verwenden, #TODO: add more examples here)

Natürlich könnten Sie argumentieren, dass diese Art von Kommentaren eigentlich gar nicht vorhanden sein sollte oder dass sie vor der endgültigen Veröffentlichung entfernt werden sollten, aber heutzutage haben Softwareprojekte sehr kurze Veröffentlichungszyklen und einige Kommentare sind immer noch relevant viele nächtliche Builds später, also sollte Ihr Freund vielleicht anfangen zu lernen, lesen (und schreiben) zwischen den Zeilen.

2
codecraft

Es ist schön, Code zu haben, der nicht kommentiert werden muss. Wenn Sie Dinge erhalten, speichern und löschen, haben wir eine ziemlich gute Vorstellung davon, was los ist, und benötigen keine Kommentare.

Manchmal wird der Code unübersichtlich und ist ein Kandidat für das Refactoring, sodass Sie in der Zwischenzeit möglicherweise einen Kommentar abgeben müssen.

Heute hatte ich eine Codezeile, die nicht das tat, was erwartet wurde. Anscheinend glaubt eine .net-Datentabelle nicht, dass eine importierte Zeile ein neuer Datensatz ist. Wenn Sie die Datensätze aus der Tabelle einfügen, geschieht nichts. Für die importierte Zeile muss zuerst der Status geändert werden. Ein einfacher Kommentar ist alles, was benötigt wird. Wenn ich also in 6 Monaten darauf zurückkomme und denke: "Wofür zum Teufel brauche ich das?" Ich werde wissen.

1
JeffO

Es ist gängige Praxis für Programmierer, Kommentare in Methoden einzufügen, wenn sie der Meinung sind, dass für andere Programmierer nicht klar ist, was der Code tut. Auch Programmierer fügen manchmal TODO-Kommentare in die Methode ein. Es ist jedoch richtig, dass Sie, wenn Sie zu viele Kommentare in Methoden haben, möglicherweise einen Schritt zurücktreten und überlegen müssen, ob Sie Dinge tun, die zu kompliziert sind, als es sein sollte. Mit anderen Worten, Sie möchten wahrscheinlich vermeiden, etwas zu kommentieren, das für andere Programmierer offensichtlich ist, da es schwieriger ist, den Code mit ihnen zu lesen.

Um den Vorschlag Ihrer Freunde positiv zu bewerten, sollten Sie sich daran erinnern, dass wir vermeiden können, zu viele Kommentare abzugeben, indem wir Variablen und Methoden richtig benennen, jede Methode klein halten und sicherstellen, dass sie nicht zu viel Personal beschäftigen.

1
knoguchi

Ich denke, der Grund, warum er das sagte, ist, dass er der Meinung ist, dass Funktionen kurz genug sein sollten, dass jede nur eine einzige konzeptionelle Operation enthält.

Ich unterschreibe diesen Glauben nicht unbedingt bis zum Äußersten (aus verschiedenen Gründen, einschließlich der Tatsache, dass das Lesen eines solchen Codes zu einem Albtraum werden kann), aber wenn dies der Fall wäre, könnte dies dazu führen, dass sie nur einen Kommentar pro Funktion haben, da es nur einen gibt Ein Konzept pro Funktion und ein Kommentar pro Konzept.

In beiden Fällen verwende ich Kommentare, wann und wo immer Code vorhanden ist, dessen Auswahl oder Verhalten nicht sofort offensichtlich ist - häufig im Zusammenhang mit Leistungsüberlegungen oder esoterischer Mathematik. Solche Dinge betreffen den Benutzer der Funktion oft nicht sofort, daher würde ich argumentieren, dass es in der Tat eine gute Idee ist, sie vor der Dokumentation zu verbergen.

1
Rei Miyasaka

Ich glaube, Ihr Freund hat über Javadoc gesprochen, das aus Ihrem Kommentar eine Dokumentation generiert, wenn diese über Ihrer Methodendeklaration liegt (und mit einem zusätzlichen Sternchen versehen ist):

/**
   get a webpage for a given url 
   @param url: the url to get
   @returns String: the http-source 
*/
public String getWebpage (String url) {
... 

Wenn Sie diesen Kommentar in die Methode einfügen, ist er nutzlos.

Daher - als Faustregel: Fügen Sie Kommentare in Java Quelle über der Methode ein.

Ausnahmen können und werden auftreten. Ich bin damit einverstanden: Verwenden Sie kurze Methoden, schreiben Sie selbstdokumentierenden Code. Javadoc als Tool fördert jedoch das Duplizieren von Kommentaren, da es sonst in der Dokumentation so nackt aussieht. :) :)

1
user unknown

Ich gebe zu, dass man in einer von Grund auf neu geschriebenen Methode ihre Funktion nur im Header dokumentieren kann. Jedoch.

Ich finde, dass Kommentare oft eingefügt werden, wenn Fehler entdeckt wurden und eine subtile Nuance übersehen wurde auch wenn die Methode nur eine einzige Verantwortung hat - was ehrlich gesagt selten im Legacy-Code der Fall ist. Außerdem sehe ich keinen Grund, einen Variablennamen zu haben, der vierzig Zeichen lang ist (auch wenn er nur an zwei Stellen verwendet wird), wenn ein kürzerer Variablenname mit einem prägnanten Kommentar später leichter verdaut und wiederverwendet werden kann. Sauber und prägnant ist am besten, aber vor allem ist es ein Kommunikationsmittel für andere Programmierer, genauso wie E-Mails, Briefe und Gedichte. Und dazu füge ich das Zitat hinzu:

"Ich habe diesen Brief nur länger gemacht, weil ich nicht die Zeit hatte, ihn kürzer zu machen."

Blaise Pascal, (1623-1662) Lettres Provinziale

1
M. Tibbits

Kommentare machen den Code nur programmiererfreundlicher. Denken Sie daran, dass Kommentare nicht ausgeführt werden.

Wenn Sie Ihren Code nach einigen Monaten lesen, erleichtern die Kommentare das Lesen des Codes.

Dadurch wird der Code wartbar, und jeder andere Programmierer, der sich den Code ansieht, kann die von Ihnen implementierte Logik leicht verstehen.

Dies bedeutet nicht, dass Sie auch für eine Methode mit wenigen Codezeilen immer Kommentare hinzufügen müssen.

Wie zum Beispiel ist der folgende Code selbsterklärend und erfordert keine Kommentare, um seine Funktion klar zu machen

public String getName(){
    return name;
}

Wenn eine Methode groß ist, fügen Sie einen Kommentar hinzu, damit sie besser lesbar ist, wenn ein Programmierer sie betrachtet.

Denken Sie daran, dass Sie beim Codieren vielleicht denken, dass der Code selbsterklärend ist, aber wenn Sie ihn nach sechs Monaten betrachten, helfen Ihnen die Kommentare, die Sie vor sechs Monaten hinzugefügt haben, auf jeden Fall, Ihnen oder einem anderen Programmierer, den Code schnell zu verstehen.

0
Alpine

Das Problem bei Inline-Kommentaren besteht darin, dass sie zusammen mit dem Code gepflegt werden müssen (gilt auch für Kommentare auf Funktions-/Methoden-/Modul-/Klassenebene, jedoch nicht in so hohem Maße). Gott weiß, wie viel Quellcode noch da draußen ist, wo die Kommentare absolut nichts mehr mit dem Code zu tun haben, den sie dokumentieren. IMO ist genauso schlecht oder schlimmer, als überhaupt keine Kommentare zu haben.

Im Idealfall sollte die Inline-Dokumentation auf folgende Situationen beschränkt sein:

  • Erklären von Code, der stark optimiert oder "knifflig" ist, zusammen mit einer Begründung für warum Der Code ist so stark optimiert oder "knifflig" ("Wir haben die Leistungsanforderung X verpasst und die Profilerstellung hat gezeigt, dass der Engpass darin liegt Abschnitt; die Optimierungen unten haben Y% Leistung gewonnen ");

  • Bezugnehmend auf einen Standard oder eine Anforderung ("DTED 0 nach dem Abstand beträgt 30 Bogensekunden");

  • Identifizieren Sie Code, der einer weiteren Analyse/Entwicklung bedarf ("TODO").

Erstes Gesetz der Codedokumentation - dokumentieren Sie nicht das Offensichtliche. Folge des ersten Gesetzes der Codedokumentation: Schreiben Sie Code, der so offensichtlich wie möglich ist.

0
John Bode

Erstens war Ihre Frage speziell Java-orientiert - was die Antwort erheblich beeinflusst.

Die Anzahl der Kommentare, die erforderlich sind, hängt stark von der Sprache ab, in der Sie arbeiten.

  • Einige Sprachen wie Java und C #) eignen sich hervorragend für das Konzept des selbstdokumentierenden Codes. In diesen Sprachen bemühen Sie sich am besten, den Code selbst so lesbar und beschreibend wie möglich zu gestalten Fügen Sie dann Inline-Kommentare nur für Dinge hinzu, die Sie in der Sprache nicht nativ beschreiben können.

  • Einige Sprachen wie SQL sind schwieriger lesbar zu machen. Die Syntax, die Reihenfolge der Auswertung, die Verschachtelung usw. können es schwieriger machen, sich selbst zu dokumentieren. Der gleiche grundlegende Ansatz gilt weiterhin: Konzentrieren Sie sich darauf, die Sprache so weit wie möglich zu verwenden, und fügen Sie dann Kommentare hinzu, um unklare oder verwirrende Bereiche auszugleichen.

Insgesamt können Sie Kommentare nicht zu 100% abschaffen, aber Ihr Ziel sollte es sein, das Bedürfnis für Kommentare so weit wie möglich zu entfernen, indem Sie den Code selbstbeschreibender gestalten. Das Ergebnis dieser Bemühungen ist normalerweise weniger Code insgesamt und besser organisierter Code. Unabhängig davon, ob noch Kommentare vorhanden sind oder nicht, bedeutet dies, dass Ihr Code viel wartbarer und zugänglicher ist - genau das sollen Kommentare in jeder Hinsicht unterstützen.

0
STW

Die Idee, dass Javadoc (oder sogar Hinweise zur automatischen Vervollständigung von Delphi) die Art und Weise ändern sollte, wie eine Person codiert (außer um Funktionen für Javadoc hinzuzufügen), ist ziemlich absurd.

Fragen Sie Ihren Freund, welcher zuerst kam, den Javac oder den Javadoc?

Das ist wie zu fragen, was zuerst kam, die Kuh oder Mrs. O'Leary


Javadoc sollte auch für Personen gedacht sein, die Ihre Klasse und Funktionen implementieren. Die Kommentare im Code richten sich an Personen, die Ihren Code verwalten. Insbesondere bei Ihren privaten Methoden sollte niemand unbedingt auf Ihren Code schauen müssen, um zu sehen, was er tut. Dafür sind die Dokumente da. Aber wenn jemand etwas aufgrund eines haarigen Fehlers optimieren muss, möchten Sie dies in Ihrer Methode kommentieren.

Er geht offensichtlich davon aus, dass 90% des Codes, bei dem es sich tatsächlich um Fehlerbehebungen handelt, alle schlecht sind. Ich habe "Der pragmatische Programmierer" noch nie gelesen, aber ich kann davon ausgehen, dass er nicht auf dieses Buch verweist.

0
Peter Turner

Ich werde meine zwei Cent jetzt werfen, da die Party ziemlich vorbei ist. Ich verwende Kommentare, wenn ich ein bestimmtes Stück Geschäftslogik beschreibe oder wenn ich etwas hinzufügen muss, um einen unvorhergesehenen Edge-Fall abzudecken.

Der Code entwickelt sich im Laufe der Zeit, um Dinge zu berücksichtigen, die vorher nicht bekannt waren. Wenn Sie also ein Pflaster anwenden, anstatt anzunehmen, dass es bekannt ist warum Sie dieses Pflaster anlegen, hilft es manchmal Um einen kleinen Block in den Code einzufügen, der besagt: "Oh, übrigens, ich musste das beheben, und hier ist die Bugtracker-Referenz, damit Sie die umgebende Konversation verfolgen können." In meinem Fall (wenn ich FogBugz verwende) würde es so aussehen ::

//Case: 1234 ~ Throttling based on unusual activity per ABC request.
Throttler myThrottler = new Throttler( oldActivity );

oder Wasauchimmer. Mein Punkt ist also, dass etwas, das fehl am Platz zu sein scheint und nicht so lesbar ist, wahrscheinlich ein guter Ort zum Inline-Dokumentieren ist. Gesammeltes Wissen ist eine schöne Sache.

Aber mein erster Punkt war meine Geschäftslogik. Ich habe buchstäblich einen Block in einer gespeicherten Prozedur, den ich gerade umschreiben werde. Dieser AM enthält einige Geschäftsregeln.

/****************************************************************
author  yourstruly
date    2010-11-18
descrip intended use is to blah blah blah
        ended up over actual measured blah blah blah according to blah blah blah
        rules from the customer are:
        If the sum of the blah blah blah is higher than the blah blah blah
        and the blah blah blah contain blah blah blah,
        and the blah blah blah is non-zero,
        recalculate the blah blah blah to fit within the blah blah blah

        Additional rules for us internally: 
        if the blah blah blah originally read blah blah blah don't blah blah blah (set to zero)

        rewritten here with (1) traceable statements for the where clauses.
        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is non-zero (9)
        and the blah blah blah is lower than the blah blah blah (4)
        and the edited blah blah blah is higher than the blah blah blah (5)
        then recalculate the blah blah blah (6)
        // See note lower in this document on the math

        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is higher than the blah blah blah (7)
        then set the blah blah blah to zero (8)

        (7) dictates the same as (4) but it's easier to do (7)
****************************************************************/

Sorry for the blah blah blah's but proprietary rules and all that ;)

Und plötzlich sehen Sie, dass in meinem Code Anforderungen (!) Als Kommentare eingebettet sind, und ich kann die Kommentare als /*(1)*/ (was ich tue) bezeichnen, damit dies für den nächsten Mitarbeiter leicht nachvollziehbar ist (was es war, und er konnte die Teile finden, die sofort optimiert werden mussten) und wenn jemand wissen will, was die Spezifikation war, kann er den Kommentar von oben lesen und wenn jemand wissen will, was der Pseudocode ist dort und wenn jemand den Pseudocode in den Code konvertieren will, dann geht es los. Für mich ist dies viel besser lesbar (für meinen Fall), da es die ursprüngliche Anfrage (aus der E-Mail herausgeschnitten) beibehält und es ermöglicht, den Gedankengang schnell und ohne allzu viel Nachdenken zu erfassen, und die Verwendung einfacher Transformationen des ermöglicht Pseudo in echten Code.

Und ja, es gibt einige Inline-Kommentare, die besagen, dass dies und das im Pseudocode nicht wie erwartet funktioniert hat, da die Anforderung nicht ganz mit den Daten übereinstimmt und wir die Daten optimieren mussten. Aber das ist mein Punkt. Wir haben die Edge-Fälle inline dokumentiert und den Pseudocode im eigentlichen Code belassen, um der Logik zu folgen, sodass wir alle wussten, was von den ursprünglichen Anforderungen erwartet wurde

0
jcolebrand