Was halten Sie von Perioden / Full Stops in Codekommentaren? [geschlossen]

27

Ich habe dies in der SO-Taverne gefragt gesehen , also poste ich die Frage hier. Ich fand es eine interessante Frage. (Natürlich gehört es nicht zu SO, aber ich denke es ist in Ordnung hier.)

Fügen Sie in Ihren Codekommentaren Punkte (oder, wie das OP schrieb, "Punkte") hinzu?

Warum , damit es aktuell bleibt ?

source-code comments coding-style grammar Moshe
quelle
2
SOmetimes tue ich und manchmal tue ich nicht. Das hängt von den Kommentaren ab und davon, was das Lesen erleichtert.
Tim,

Antworten:

29

Punkt ist für das Beenden von Sätzen, aber wenn ein Kommentar nur aus einem Satz besteht, der von Code umgeben ist, dann ist Punkt meiner Meinung nach nicht erforderlich. Manchmal schreibe ich den ersten Buchstaben nicht groß. Für einen detaillierten mehrzeiligen Kommentar ist hingegen eine vollständige Interpunktion erforderlich.

// This function returns an average of two integers. Note that it may
// return an irrelevant result if the sum of a and b exceeds the int
// boundaries.

int avg(int a, int b)   // make it static maybe?
{
    // A better algorithm is needed that never overflows
    return (a + b) / 2; 
}
Mojuba
quelle
4
+1. Das sieht meinem Kommentierungsstil so ähnlich, dass ich ein falsches Deja Vu habe. :)
Bobby Tables
26
Nein, Punkt dient zum Markieren des Satzendes. Es ist unerheblich, ob Sie eine oder mehrere haben.
Turm
2
<joke> Wäre es nicht besser, nach Überschreitungen der Int-Grenzen zu suchen? </ joke>
Dan Rosenstark
2
@Yar: ein Durchschnitt liegt immer zwischen a und b, die per definitionem immer innerhalb der Grenzen liegen, oder? ;)
Mojuba
8
Alle meine Zeichenfolgen sind mit Null beendet, daher sollte ein richtiger Kommentar immer mit '\ 0' enden. Sie möchten nicht, dass der nächste Typ, der sich Ihren Code ansieht, über das Ende seiner Gedanken hinaus liest, oder?
CodexArcanum
26

Ja, da die Kommentare in Englisch verfasst sind und korrektes Englisch Satzzeichen verwendet.

Dominique McDonnell
quelle
2
Wie wäre es mit SMS?
Moshe
4
@Moshe, SMS sind kaum ordentliches Englisch.
Dominique McDonnell
8
Kaum richtig Englisch, aber ich verwende immer noch Interpunktion in ihnen. Die Zeichensetzung soll den Leser genau darüber informieren, was der Autor beabsichtigt hat - dies gilt für jede Sprache, IMHO.
cjmUK
@cjmUK, Lol, ja, und ich auch. Ich dachte, Moshe meinte es als einen Grund, warum wir keine Interpunktion verwenden würden, da ich regelmäßig Nachrichten wie "Das würde mich dort verabschieden" erhalte, die mich die Mauer hinauf treiben
Dominique McDonnell
Ich werde jetzt ganz
alleine sein
17

Fügen Sie in Ihren Codekommentaren Punkte (oder, wie das OP schrieb, "Punkte") hinzu?

Warum, um es aktuell zu halten?

Aus dem gleichen Grund füge ich sie hinzu, wenn ich "normalen" Text schreibe - sie sind ein Teil der Schriftsprache, und an ihnen sollte nichts Besonderes sein. Ich benutze sie gleichermaßen, wenn ich einen Satz (eine Zeile) als auch ganze Absätze schreibe.

Der Quellcode ist kein normaler Text, daher verwenden wir unterschiedliche Regeln. Einfach ;-)

Turm
quelle
Ein Freund von mir fängt niemals Wörter in E-Mails ein ... weil sie im Internet sind. Für mich ist es in Ordnung, wenn Sie Ihr Schreiben an technische Einschränkungen wie SMS anpassen, aber wie unterscheiden sich E-Mails oder Quellcode von Text in Briefen und Büchern?
LennyProgrammers
1
@ Lenny222 - Nicht sicher, was Sie hier fragen. E-Mails sollten wie normaler Text geschrieben werden. als würdest du einen Brief schreiben, wie du sagst. Wie sie tatsächlich geschrieben sind (und SMS, Junge, lass mich nicht mit SMS anfangen :) Der Quellcode unterliegt nicht den gleichen Regeln wie normaler Text, da er seine eigenen Syntaxregeln hat.
Rook
2
Für mich sind Quellcodekommentare dazu gedacht, von Menschen gelesen zu werden. Warum sollte es einen Unterschied machen, ob sich einige Informationen in einem separaten Spezifikationsdokument befinden oder in einem Quellcodekommentar eingebettet sind?
LennyProgrammers
@ Lenny222 - Mir ist gerade etwas eingefallen, nur damit es kein Missverständnis zwischen uns gibt. Sprechen wir jetzt über den Quellcode oder die darin eingebetteten Kommentare? Wenn es der zweite Fall ist, dann entschuldige ich mich, weil ich Sie missverstanden habe. In diesem Fall gelten dieselben Regeln wie für normalen Text (für Kommentare). Im eigentlichen Quellcode (der vom Compiler / Interpreter gelesen wird) sehe ich nicht, wie die gleichen Regeln folgen könnten.
Turm
1
Ja, ich denke, wir sind uns einig, ohne es zu wissen. ;)
LennyProgrammers
9

Wenn Sie Kommentare schreiben, würde man hoffen, dass sie auf Englisch geschrieben sind. In diesem Fall sollte man richtig interpunktieren. Andernfalls wäre faul.

schnell_nun
quelle
1
Fristen gelten für das Ende eines Satzes. Kommentare sind nicht unbedingt vollständige Sätze.
John B. Lambe
Kommentare sollten im Allgemeinen Sätze sein. Wenn nicht, sollte ich fragen, warum nicht. Wenn Ihre Kommentare so kurz sind, dass es sich nicht um Sätze handelt, sind sie möglicherweise offensichtlich und daher überflüssig?
quick_now
5

Wenn ich einen ganzen Satz (oder mehr) schreibe, dann ja. Wenn nicht, dann manchmal nein, aber normalerweise immer noch ja.

Ich werde auch manchmal verrückt und benutze Ausrufezeichen, Fragezeichen usw.;)

Was den Grund angeht, so liegt es zum Teil daran, dass ich nur so besonders bin, und zum Teil daran, dass eine angemessene Zeichensetzung viel Klarheit schaffen kann.

Adam Lear
quelle
Wenn Sie Fragezeichen verwenden, verstehen Sie Ihren eigenen Code?
Moshe,
@ Moshe: Diese sind normalerweise in TODOs, wenn ich meinen eigenen Code möglicherweise noch nicht vollständig verstehe.
Adam Lear
2
@ Moshe - Warum können Kommentare keine Fragen enthalten? Fragen können rhetorisch sein. In der Tat, ich oft uns? in meinen Kommentaren - Wenn ich bedingten Code beschreibe, anstatt die Logik trocken zu erklären, ist es oft klarer, die Logik als eine Frage zu beschreiben. ZB "Wurden die Qualifizierungskriterien erfüllt? Wenn Nein, Warnung für Benutzer anzeigen."
cjmUK
1
Bei der Arbeit mit großen Projekten und vielen Mitarbeitern finde ich oft die fragenden Kommentare am wichtigsten.
LennyProgrammers
3

Die anderen Antworten und ihre Beliebtheit haben deutlich gemacht, dass Punkte in längeren Kommentaren sehr geschätzt werden und wahrscheinlich in Einzeilern vermieden werden können.

Ein weiterer Punkt, der relevant sein könnte, ist das Vermeiden von Ausrufezeichen, insbesondere von Mehrfachnennungen . Beispiel:

    // Though loop is labor-intensive, performance is fine with with 95K cases!!!

und

    // This code really sucks!

Andererseits sind Fragezeichen manchmal sehr nützlich:

    // TODO: What does Crojpler.bway() actually do?
Dan Rosenstark
quelle
1

Es hängt davon ab, ob. Wenn ich einen großen, richtigen Absatz schreibe, der erklärt, was ein Codeblock tut, dann setze ich ihn wie jedes andere richtige Stück richtig. OTOH, wenn ich nur eine Codezeile kommentiere, dann nicht.

Warum? - Ähnlich wie beim Schreiben von E-Mails mit der richtigen Schreibweise, während in SMS-Nachrichten möglicherweise kurze Sätze verwendet werden. In einem Fall setze ich mich hin, um einen richtigen Textblock zu schreiben, also mache ich es einfach automatisch "richtig", während es in dem anderen Fall nur eine kurze Notiz ist, um einen Punkt zu vermitteln.

Echte Beispiele aus meinem Code:

Kurznotiz Kommentar:

// check for vk_enter

Dokumentation der "richtigen" Methode:

// This method sets up a workspace tab with the given name. Each MDI window has a parent
// workspace specified when it's saved. The code which loads each MDI window then point it to
// the correct workspace.
Bobby Tische
quelle
.NET-Entwickler, was? ;-)
Moshe
@ Moshe: Java eigentlich. Dies ist Code aus einem sehr großen und komplexen Applet, im Grunde genommen wie eine Desktop-Swing-App, mit der Ausnahme, dass er im Browser ausgeführt wird. :)
Bobby Tables
Ich denke, dass MDI ein .NET-Begriff ist.
Moshe,
@ Moshe: Nein, es ist generisch ( en.wikipedia.org/wiki/Multiple_document_interface ).
Bobby Tables
1

Ja, ich denke, auf diese Weise erstellen Sie eine gute Codierungskonvention und es wird auch ein gut lesbarer Code für eine dritte Person erstellt, die Ihren Code überprüft.


quelle
1
Was ist mit einer zweiten Person?
Daviewales
0

Ich werde beim Erstellen von XML-Kommentaren , die in IntelliSense und in unserer generierten Dokumentation zu sehen sind, immer die richtigen Groß- und Kleinschreibung und Interpunktion verwenden . Dies sind viel formalere Konstrukte und sollten als solche behandelt werden.

Kommentare, die nur im Hauptteil eines Codeblocks angezeigt werden, sollten jedoch einfach so klar wie möglich sein. Es liegt am Programmierer, wie sie das erreichen.

Matt DiTrolio
quelle