Wenn ich ein typisches if-else-Konstrukt in einer beliebigen Sprache schreibe, frage ich mich, wie ich es am besten (in Bezug auf Lesbarkeit und Übersicht) kommentieren kann. Besonders wenn ich die else-Klausel kommentiere, fühlen sich die Kommentare für mich immer unangebracht an. Nehmen wir an, wir haben ein Konstrukt wie dieses (Beispiele sind in PHP geschrieben):

if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Ich könnte es so kommentieren:

// check, what kind of magic should happen
if ($big == true) {
    // do some big magic stuff
    bigMagic();
} else {
    // small magic is enough
    smallMagic()
}

oder

// check, what kind of magic should happen
// do some big magic stuff
if ($big == true) {
    bigMagic();
}
// small magic is enough
else {
   smallMagic()
}

oder

// check, what kind of magic should happen
// if:   do some big magic stuff
// else: small magic is enough
if ($big == true) {
    bigMagic();
} else {
    smallMagic()
}

Was sind Ihre Best-Practice-Beispiele, um dies zu kommentieren?

Ich bevorzuge entweder:

if ($magic == big) {
    bigMagic();
}
else {
    smallMagic();
}

oder:

if ($magic == big) {
    // big magic requires a big surprise, so I'm telling you about it here
    surprisingThing();
}
else {
    // give a magical feeling even if $magic is noMagicAtAll
    smallMagic();
}

Es scheint ein wenig albern zu sein, einen Kommentar zu schreiben, in dem erklärt wird, was Ihr Zustand überprüft, es sei denn, der Code gibt dies nicht eindeutig an. Selbst dann ist es besser, den Code neu zu schreiben, um ihn so klar wie möglich zu gestalten. Das Gleiche gilt für die Körper der Bedingungsblöcke - wenn Sie den Grund für die Ausführung von etwas Offensichtlichem angeben können, tun Sie dies, anstatt zu kommentieren.

Ich bin nicht mit der Philosophie einverstanden, niemals Kommentare zu schreiben, aber ich glaube daran, Kommentare zu vermeiden, die aussagen, was der Code sagen soll. Wenn Sie einen Kommentar wie "Überprüfen Sie, welche Art von Magie passieren soll" schreiben, wenn der Code sagen könnte if ($magic == big) {..., hören die Leser sehr schnell auf, Ihre Kommentare zu lesen. Durch die Verwendung von weniger, aussagekräftigeren Kommentaren erhält jeder Ihrer Kommentare einen höheren Stellenwert, und die Leser achten mit größerer Wahrscheinlichkeit auf die Kommentare, die Sie verfassen.

Die Auswahl aussagekräftiger Namen für Ihre Variablen und Funktionen ist wichtig. Ein ausgewählter Name kann dazu führen, dass im gesamten Code keine erklärenden Kommentare erforderlich sind. In Ihrem Beispiel $magicoder vielleicht $kindOfMagicscheint es ein besserer Name zu sein als $bigin Ihrem Beispiel, da es sich um die "Art von Magie" handelt, die getestet wird, nicht um die "Größe" von etwas.

Sagen Sie so viel wie möglich in Code. Speichern Sie Prosa für die Fälle, die mehr Erklärung erfordern, als Sie vernünftigerweise in Code schreiben können.

Versuchen Sie es mit erklärenden Variablennamen

Kommentare können großartig sein, aber wenn möglich, sollte der Code selbstdokumentierend sein. Eine Möglichkeit hierfür sind erklärende Variablennamen. Zum Beispiel stattdessen:

if (user.has_sideburns && user.can_gyrate) {
  // This user is a potential Elvis impersonator

}

Ich würde eine benannte Variable bevorzugen:

is_potential_elvis_impersonator = user.has_sideburns && user.can_gyrate

if (is_potential_elvis_impersonator) {
  ...
}

Nur um einige Kommentare zu vervollständigen:

Die ordnungsgemäße Verwendung von Kommentaren soll unser Versäumnis ausgleichen, uns im Code auszudrücken. Beachten Sie, dass ich das Wort Fehler verwendet habe. Ich meinte es. Kommentare sind immer Fehler. Wir müssen sie haben, weil wir nicht immer herausfinden können, wie wir uns ohne sie ausdrücken können, aber ihr Gebrauch ist kein Grund zum Feiern. ( Clean Code von Robert C. Martin )

BTW: Ich empfehle dieses Buch.

Kommentare sollten den Code nicht umschreiben, sondern erklären Dinge, die nicht im Code enthalten sind (größeres Bild, warum, warum keine Alternative gewählt wurde ...) Und Ihre Beispielkommentare sind genau das: Umschreiben des Codes.

Sie haben manchmal das Gefühl, dass zu Beginn des elseZweigs eine Umschreibung erforderlich ist , aber dies ist oft ein Zeichen dafür, dass Ihr thenZweig zu groß ist.

In Ihrem speziellen Beispiel sind Kommentare wahrscheinlich nicht erforderlich. Wie Caleb sagte , wenn der Code klar geschrieben ist und Variablen semantische Namen haben, ist es weniger wahrscheinlich, dass Anweisungen kommentiert werden müssen.

Vergleichen Sie Ihr Snippet damit:

if ($x) {
    func1();
} else {
    func2();
}

In diesem Fall möchten Sie auf jeden Fall Kommentare verwenden, um zu beschreiben, was x, func1 und func2 darstellen (und die Person zu schlagen, die die Dinge nach diesem Schema benannt hat, besonders wenn Sie es waren). Man kann nicht einmal sagen, ob $xes sich um einen Booleschen handeln soll. Aber auch dies ist ein Fall, in dem Sie nicht unbedingt Kommentare benötigen, wenn Sie umgestalten und umbenennen können.

Im Allgemeinen schreibe ich gerne Kommentare für logische Blöcke, die Dinge beschreiben, die der Code nicht alleine kann. Ein Einzeiler pro ~ 10-20 Zeilen, der beschreibt, was die folgenden wenigen Zeilen auf einer höheren Abstraktionsebene leisten (z. B. // Make the right amount of magic happenfür Ihr Beispiel), hilft Ihnen, sich zu orientieren und gibt einem neuen Prüfer einen Einblick darüber, was Sie wann tun .

Ich schreibe diese Einzeiler tatsächlich oft ein, bevor ich mit dem Schreiben von Code beginne, damit ich nicht den Überblick über den Fluss verliere, den das Segment haben soll.

Wenn Sie es wirklich vorziehen (oder ein Mandat erfordert), Klauseln in einem if-Block zu kommentieren, ungeachtet der Lesbarkeit des Codes, empfehle ich:

// Broad description of block
if (something) {
    //Do this because something
    something();
} else {
    //Do this because !something
    somethingElse();
}

Ich denke, es ist das sauberste, weil der Kommentar mit dem Code übereinstimmt, zu dem er gehört. Ein Kommentar, der beschreibt, was Code tut, sollte so nah wie möglich an dem Kommentar sein, den er beschreibt.

if (IsWeekDay(day))
{// weekday -> alarm at 7am
   ...
}
else if(day == DayOfWeek.Saturday)
{// saturday -> alarm at 11am
   ...
}
else
{// (sunday) -> no alarm
   ...
}

Ich halte meine Klammern in einer Reihe und setze sie direkt hinter die Klammer.

[Condition] -> [pseudo-code]

Ansonsten bedeutet es technisch, dass alle anderen Bedingungen fehlgeschlagen sind, daher verwende ich normalerweise runde Klammern.

([Condition]) -> [pseudo-code]

Hinweis: Dies ist für C #.

Ich versuche, Kommentare innerhalb des Blocks zu verwenden, die angeben, was dieser Block tut (Ihr erstes Beispiel).

Wo dies irgendwie zusammenbricht, ist bei der Verwendung elseif. Ich benutze Basic, damit es keinen expliziten Endeblock gibt, und muss oft kommentieren, welche Bedingung überprüft wird, wenn sie zu lang ist (natürlich mit einem Zeilenumbruch).

'Check XYZ
If Condition1 then
  'We need to do T and S
  DoCodeFor1();

'Check ABC
ElseIf Condition1 then
  'This requires something else to be done
  DoCodeFor2()

Else
  'We have no other option than to...
  DoCodeFor3()

End If

• Halten Sie Ihre bedingten Blöcke wirklich kurz.
• Rufen Sie eine Methode mit einem aussagekräftigen Namen auf, wenn der bedingte Code mehr als ein oder zwei Zeilen lang sein soll.
• Verwenden Sie aussagekräftige Namen für Ihre Variablen.
• Stellen Sie sicher, dass die bedingte Anweisung in ihrer Bedeutung klar und nicht verschleiert oder lang ist. Wenden Sie eine Methode an, wenn dies dazu beiträgt, die Inhalte sauber und lesbar zu halten.

Wenn all dies fehlschlägt, fügen Sie vor der if-Anweisung einen sehr kleinen beschreibenden Kommentar hinzu, um Ihre Absicht zu verdeutlichen. Ansonsten sollte es eigentlich gar keinen Kommentar geben.

In C ++ oder C # würde ich normalerweise keine einfachen Fälle kommentieren (wenn klar ist, was passiert) und diese Art von Stil zum Kommentieren des finalen Sonst ...

if (pattern == AAA)
{
  DoSomethingAAA();
}
else if (pattern == BBB)
{
  DoSomethingBBB();
}
else // if (pattern == CCC)
{
  DoSomethingCCC();
}