Kommentar vor oder nach dem entsprechenden Code [geschlossen]

34

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.

msh210
quelle
3
Überlegt, was passiert, wenn Sie es nachher setzen. Programmierer las den Code. Sagen Sie sich WTF das tut ??? Siehe den Kommentar. Lesen Sie den Code erneut. Verstehe es irgendwann oder gib auf. Sei also nett und vermeide Teil 1 und 2, indem du ihn oben drauf legst.
Deadalnix
@deadalnix, danke, das scheint auch der Kern der Antwort von Dipan Mehta zu sein . (Vielen Dank auch an alle bisherigen Antwortenden und jeweils +1 an jeden.)
msh210

Antworten:

22

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.

Dasheddot
quelle
1
Häkchen, da dies die einzige (bisher) Antwort ist, die die Frage, die nicht nach persönlicher Präferenz, sondern nach Standardarbeitsanweisungen strebt, klar beantwortet, indem sie MSDN zitiert.
msh210
1
@ msh210: Also bevorzugen Sie eine Microsoft-Präferenz gegenüber den persönlichen Präferenzen anderer guter Programmierer? ABER Sie wissen, wie Microsoft die ungarische Notation als Standard falsch verstanden hat? Ja? Machst du? Vertraue nur dem gesunden Menschenverstand, laufe nicht immer mit der Horde oder folge dem größten Bullen.
Falcon
2
@ Falcon, ich habe noch nie von der ungarischen Notation gehört, und ich vermute, dass die Präferenz von MSDN zumindest das Ergebnis zahlreicher Beiträge von MS-Mitarbeitern war. Die Antworten hier sind dagegen individuell verfasst.
msh210
43

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.

Ryathal
quelle
9

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.

Joshua Smith
quelle
7

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.

Dipan Mehta
quelle
6

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.

Caleb
quelle
4

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

Lucero
quelle
Lesen Sie die Frage erneut: Gibt an, dass in einer separaten Zeile nach einem Kommentar gefragt wird.
msh210
2
@ msh210 Das ist eine perfekte Antwort. msgstr "Kommentare vorher schreiben". Es ist noch detaillierter und gibt einen möglichen Grund an, warum Sie denken könnten, dass sie hinter "Außer wenn sie kurz sind und am Ende der Zeile stehen."
23.
3

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.

Brian Stinar
quelle
10
Selbstdokumentierender Code kann "was" und "wie" beantworten, aber egal wie gut geschrieben, Code allein kann die Frage "warum" selten beantworten. Wenn es ein umfassendes Anforderungsdokument gibt, finden Sie dort manchmal die Antwort. Ansonsten sind Kommentare oft alles, was Sie zu erklären haben, warum der Code tun muss, was er tut.
Ed Staub
1
Ich stimme nicht zu. Wie @EdStaub sagt, beantworten Kommentare eine andere Frage auf einer anderen Ebene. Auch Code ist nicht unbedingt Open Source. Und selbst wenn es so ist, möchte ich keinen Framework-Quellcode lesen, um zu wissen, wie man ihn verwendet.
23.
4
Sie haben sich offensichtlich nie mit Hardware beschäftigt (oder auch nicht mit schlecht geschriebener Software). Vor kurzem habe ich eine Spezialklasse geschrieben, um mit einem ziemlich undurchsichtigen (und kribbeligen ) Motorcontroller zu sprechen . Es hat alle möglichen seltsamen Anforderungen an die Schnittstelle. Ohne eine einzige Funktion pro Zeile ist es nicht möglich, den Code verständlich zu machen, ohne ihn zu kommentieren.
Fake Name
3
@ Brian, "Warum" -Fragen sind oft sehr feinkörnig - z. B. um Fehler in einer API herumzukommen und / oder zu erklären, dass etwas, das falsch aussieht, tatsächlich korrekt ist. Das sind nur einige Beispiele. Ich würde nicht sagen, dass Kommentare ein umfassendes Anforderungsdokument sind. Aber ich würde auch nicht versuchen, die Gründe für jedes kleine Implementierungsdetail in einer Anforderungsspezifikation (oder sogar einer Konstruktionsspezifikation) zu erläutern.
Ed Staub
1
@codesparkle - Ich bin damit einverstanden, dass Kommentare, die als Ausrede zur Vermeidung von Refactoring verwendet werden, im Allgemeinen schlecht sind. Dies bedeutet jedoch nicht, dass alle Kommentare schlecht sind, sondern dass Kommentare, die auf diese Weise missbraucht werden. Tatsache ist, dass es eine Reihe von Situationen gibt, in denen Kommentare die beste Option sind, um ungerade Codierungsanforderungen zu klären.
Fake Name
2

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.

Dan Ray
quelle
2

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){ ... }  
Larry OBrien
quelle
5
Beide Codeblöcke haben Kommentare vor dem Code, den sie kommentieren.
msh210
Ihre eigenen Kommentare negiert Ihre "After Case" hehe :) Umarmungen und +1 für die Erstellung eines weihnachtlichen Themenbeispiels
Ahmed Masud
1
@ msh210 Ich sehe meine Kommentare im ersten Beispiel als Kommentare zum Test if (christmas) und nicht als Kommentare zu den folgenden Funktionen (das heißt, sie sagen "Was bedeutet es, dass wir hier sind?"). Sie gehen voran ein Codeblock, aber ich habe noch nie einen Code gesehen, der ... code () hatte; Code(); / * Kommentar, der den vorhergehenden Block erklärt * /} und die Frage nicht so
aufgefasst hat
1

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.

Thomas Owens
quelle
1

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.

Mike Nakis
quelle
Wie ich immer sage: Ihre Ablehnung ohne Erklärung hilft mir nicht, ein besserer Mensch zu werden. Hab dich auch lieb!
Mike Nakis
1

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 ...

Niranjan Singh
quelle
1

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.

Mücke
quelle