Kommentar vor oder nach dem entsprechenden Code [geschlossen]

Angenommen, ein Kommentar passt nicht in die Zeile, für die er gilt (oder kann nicht), sollte man den Kommentar vor oder nach dem Code schreiben?

Nun, wo auch immer zukünftige Leser den Umfang des Kommentars am besten verstehen werden. Mit anderen Worten, überall dort, wo die meisten Programmierer / Skripter solche Kommentare abgeben.

Also wo die meisten Programmierer / scripters setzt einen Kommentar: vor oder nach dem Code?

Wenn Ihre Antwort nur auf bestimmte Sprachen zutrifft, geben Sie bitte an, welche.

Und wenn Sie eine akzeptierte Spezifikation oder Anleitung zitieren können, die Ihre Antwort unterstützt, umso besser.

Ich würde entweder inline kommentieren oder vor dem Code, für den der Kommentar gelten soll. Der Sinn von Kommentaren besteht darin, ein grundlegendes Verständnis für die Funktionsweise des Codes zu erlangen, ohne den Code selbst lesen zu müssen. Daher ist es viel sinnvoller, die Kommentare vor dem Code zu platzieren, den sie beschreiben.

Microsoft empfiehlt, die Prozeduren mit einem kleinen Kommentar zu beginnen. (Sie erwähnen das Kommentieren nach Prozeduren nicht) MSDN Der Link handelt von VisualBasic, aber er gilt für die meisten Programmiersprachen, die ich denke.

Ich bevorzuge es, dass Kommentare über dem Code stehen, auf den sie sich beziehen. Es ist nur sinnvoller, einer Person, die den Code liest, zu erklären, was auftaucht, anstatt zu versuchen, auf den vorherigen Code zu verweisen, um zu erklären, dass einige unordentliche Codezeilen einen Fehler behoben haben, der schwierig war Fass es also nicht an.

Ich denke, Code wird im Allgemeinen von oben nach unten gelesen. Wenn nicht anders, würde mich das Muskelgedächtnis veranlassen, einen Kommentar mit der nächsten Codezeile darunter zu verknüpfen.

In der Regel sollte sich der Kommentar oben in der Zeile befinden und auf den gleichen Einzug wie die Arbeit folgen. Zum Beispiel Kommentare über dem Hauptteil der Funktionen und ein Kommentar direkt über dem Start eines kritischen Algorithmus.

Der Grund ist, wenn jemand anfängt, es zu lesen, wird die offensichtliche Frage, warum etwas so gemacht wird; wo, wie die Person nicht weiß, bis zu welchem ​​Punkt man für die Antwort scrollen muss. Wenn es oben ist, ist es genau dort zu sehen.

Wo also schreiben die meisten Programmierer / Skripter einen Kommentar: vor oder nach dem Code?

In vielen Jahren des Programmierens mit einer Vielzahl von Sprachen kann ich mich nicht erinnern, Code in einer Sprache gesehen zu haben, in der ein Kommentar in einer neuen Zeile nach dem Code steht, auf den er sich bezieht. Zumindest in den USA kommentiert der De-facto-Standard entweder vor dem Code oder in derselben Zeile nach dem Code. Wenn Sie Ihre Kommentare nach dem entsprechenden Code verfassen, werden ein Drogentest, eine psychiatrische Bewertung und / oder ein Datum mit einer Zange und einer Lötlampe verlangt.

Die einzige Ausnahme, die mir einfällt, ist ein Kommentar, der das Ende eines zuvor kommentierten Abschnitts markiert, wie dieser:

// BEGIN CRITICAL SECTION
lock(&myMutex);

doSomeThreadUnsafeStuff();

unlock(&myMutex);
// END CRITICAL SECTION

Jef Raskin schrieb einen wohlüberlegten Aufsatz über Kommentare , die es wert sind, gelesen zu werden. Er sagt nicht, ob er seine Kommentare vor oder nach dem Code setzt, aber er sagt, dass er sie nie inline setzt, und ich würde viel Geld wetten, dass er sie auch nicht danach setzt.

Versuchen Sie nur zu kommentieren, wo dies wirklich notwendig ist. Der Code sollte nach Möglichkeit versuchen, sich selbst zu dokumentieren.

Davon abgesehen kann die Platzierung abhängen: Wenn Sie eine separate Zeile für den Kommentar verwenden, setzen Sie sie vor den eigentlichen Code. Wenn Sie es in der gleichen Zeile haben, setzen Sie es nach.

// this workaround is required to make the compiler happy
int i = 0;

Vs.

int i = 0; // make the compiler happy

Aber nie:

int i = 0;
// this workaround is required to make the compiler happy

Ich bin eigentlich kein großer Fan von Kommentaren. Während eines Software-Engineering-Kurses wurde mir die Idee des selbstdokumentierenden Codes vorgestellt. Der Code ist die einzige zu 100% garantierte korrekte Dokumentation von sich selbst - Kommentare müssen aktualisiert, sorgfältig erstellt und relevant sein, andernfalls handelt es sich um Fallen, die schlimmer als kein Kommentar sein können. Erst als ich anfing, in einem C ++ - Shop mit einem strengen Styleguide und aussagekräftigen Namenskonventionen zu arbeiten, verinnerlichte ich dieses Konzept wirklich.

Manchmal sind Kommentare erforderlich. Eine sorgfältige Benennung von Variablen, eine sinnvolle Verwendung von Leerzeichen und Gruppierungen sowie eine sinnvolle logische Organisation des Codes selbst machen den Kommentar überflüssig.

Dies ist wirklich eine Negation des Anspruchs und der Gültigkeit Ihrer Frage, im Gegensatz zu einer Antwort auf die Frage, die Sie hatten. Ich denke immer noch, dass es relevant ist und dir vielleicht hilft, und ich war kein Idiot. Wenn nicht, werden die -1 mich dominieren.

Wenn der Kommentar vor dem Code angezeigt wird, hat der Leser einen Kontext für den Code, auf den er stoßen soll. Viel humaner, als ihnen den Code zuzuwerfen und zu erklären, nachdem sie bereits verwirrt sind.

OK, ich mache den Fall "nach": Der Code sollte immer die primäre Dokumentation sein, während der Kommentar (der keine semantische Bedeutung hat) einer Erklärung in Klammern gleicht. Wenn Sie also den Kommentar unter den erklärungsbedürftigen Code stellen, bleibt der Code die wichtigste Erklärung und wird nur zur Verdeutlichung verwendet. Zum Beispiel,

if(date == CHRISTMAS){
     //Deliver presents
     val (nice, naughty) = partition(boysAndGirls);
     prepSled();
     findRudolph();
     putOnRedSuit();
     ...
}else{
     //Not Christmas, build toys
     monitorElves();
     ...
}

Wenn Sie den Kommentar vor den Test stellen, neigt der Leser dazu, den Kommentar als primäres Element zu lesen und den Code möglicherweise nicht genau zu lesen, ohne zu bemerken, dass er irregeführt wurde:

 //Check to see if it's a leap year
 if(year % 4 == 0){ ... }  

Um einige Ideen aus dem technischen Schreiben zu übernehmen (zumindest in englischer Sprache), werden Dinge wie Anmerkungen und Warnhinweise in der Regel vor die Anweisungen oder Abschnitte gestellt, auf die sich die Anmerkung oder Warnhinweise beziehen.

Ich verstehe nicht, warum Code nicht als eine Form des technischen Schreibens angesehen werden kann - jeder Block ist eine Anweisung. Wie die englische Sprache werden die meisten Programmiersprachen von links nach rechts und von oben nach unten gelesen. Kommentare sind Anmerkungen zum Code. Sie können Fehler identifizieren, die behoben werden müssen, oder Dinge, die ein zukünftiger Entwickler beachten muss.

Nach dieser Beziehung erscheint es angemessener, den Kommentar über den Codeblock zu setzen, auf den er verweist.

Je nachdem, um welche Art von Kommentar es sich handelt, muss ein Kommentar möglicherweise über oder unter einem Codeteil stehen: Wenn er eine kurze Erläuterung der Funktionsweise des Codes enthält, muss er dem Code vorangestellt werden. Wenn es ein technisches Detail der Funktionsweise des Codes ausführlich erläutert, muss es dem Code folgen.

Glücklicherweise kann ein Kommentar über oder unter einem Codeteil stehen und dennoch keine Zweifel daran lassen, zu welchem ​​Codeteil er gehört, wenn Leerzeilen ordnungsgemäß verwendet werden. Natürlich werden Programmierer, die nicht auf die Verwendung von Leerzeilen achten, nicht wissen, wovon ich spreche. Wenn Sie einer von denen sind, überspringen Sie diese Antwort und fahren Sie mit Ihrem Leben fort. Programmierer, die auf Leerzeilen achten, wissen jedoch sehr gut, dass Leerzeilen zum Aufteilen von Code in logische Einheiten verwendet werden. Wenn Sie also Folgendes sehen:

[blank line]
/* comment */
{ code }
[blank line]

Sie wissen, dass der Kommentar zum Code gehört und Ihnen sagt, was der Code tut. Wenn Sie folgendes sehen:

[blank line]
{ code }
/* comment */
[blank line]

Wieder wissen Sie sehr gut, dass der Kommentar zu diesem Code gehört, und es ist eine Klarstellung darüber, wie der Code das tut, was er tut.

Kommentare oben ist am besten.

Wenn Sie Kommentare einfügen müssen und Ihr Code nicht selbsterklärend ist, dann würde ich lieber nicht durch einen Codeblock verwirrt werden, dann sehen Sie "ahh, das sollte es tun".

Code kann (und sollte) "selbstdokumentierend" sein, aber wenn Sie jede Codezeile lesen und verstehen müssen, um zu verstehen, wie eine Methode funktioniert. If a summary/ comment found in the last of method then it will be lot of coding time is spent searching for the chunk of code that we wish to edit. By using a summary comment on each block, I can quickly zero in on the block that is relevant to my task.

Als ich mich mit diesem Thema befasst habe, stellte ich fest, dass die meisten computerlesbaren Dokumentationssysteme (Doc XML, Doxygen, Java doc usw.) erwarten, dass der Kommentar vor dem Code kommt, auf den er sich bezieht. Es ist besser, mit diesem Standard kompatibel zu bleiben.

Ich bin auch mit dem SO-Thread einverstanden. Sollten wir Kommentare nach den Codeblöcken anstatt vorher hinzufügen? ..

Ich würde auch lieber vorne wissen ...

Ich konvertiere häufig Kommentare (meine wie auch von anderen geschriebene) in Protokollanweisungen auf Ablaufverfolgungsebene. Dadurch ist es in der Regel viel einfacher zu verstehen, wo es platziert werden soll.

    // Return an empty list if we failed to retrieve anything
    // I convert above to:
    logger.trace("Return an empty list if we failed to retrieve anything");

Ein zusätzlicher Vorteil ist, dass ich bei schwierigen Bedingungen die Protokollverfolgung aktivieren und ein detaillierteres Ausführungsprotokoll erhalten kann.