Hat der Kommentarstil Einfluss darauf, wie Leser Code verstehen?


8

Diese Frage beschäftigt mich seit 2 Monaten.

Vor einiger Zeit gab mir ein Freund, der ein großartiger Programmierer ist, einige Beispielcodes, und zum ersten Mal bemerkte ich einen einzigartigen Stil beim Organisieren von Kommentaren. Er bemühte sich, Kommentare so zu gestalten, dass ich mich mit dem Code selbst besser auskenne. Zum Beispiel:

/////////////////////////////////////////////                                                   //                                             //
//  This code prints a basic "Hello world" //
// message to the console screen. You can  //
// change the text in the brackets.        //
//                                         //
/////////////////////////////////////////////

#include <iostream>

int main() {
  cout << "Hello world";

}

wenn er einfach hätte schreiben können

/* This code prints a basic "Hello world" message to the console, change text in brackets */

 #include <iostream>

int main() {
  cout << "Hello world";

}

Diese Art von Beispiel nur in größerem Maßstab. Ich finde das in beruflichen Situationen etwas unproduktiv, aber in einer Lernsituation scheint es ideal.

Die Frage ist hier, ob der Kommentarstil das Verständnis des Lesers für Code beeinflusst. Meiner persönlichen Meinung nach ist Option 1 für das Auge hübscher und leichter zu befolgen als Nummer 2. Beeinflusst die Art und Weise, wie Sie Code kommentieren, die Fähigkeit, Ihren Code zu verstehen, oder wird nur Zeit und Platz verschwendet?


Beide Beispiele sind gute Beispiele für schlechte Kommentarstile für professionellen Code. Kommentarfelder sollten nicht verwendet werden, und Blockkommentare sollten ebenfalls vermieden werden. Pädagogen scheinen Kommentarfelder zu lieben.
Ryathal

Antworten:


5

Ja

Das Layout eines Programms aus der Perspektive von Leerzeichen und Kommentaren hat einen großen Einfluss darauf, wie gut ein Entwickler Ihren Code lesen kann.

Prettier to the eye and more easy to follow sind subjektiv und werden nicht für jeden Programmierer gleich sein.

Abgesehen davon bevorzugen einige Entwickler, mehr Code gleichzeitig auf dem Bildschirm zu sehen, während andere mehr Leerzeichen / Kommentare bevorzugen.

Am Ende des Tages werden Sie es bequemer haben, Code zu lesen, als Sie es gewohnt sind.

Onkel Bob Martin, Autor von Clean Code, argumentiert, dass Kommentare häufig verwendet werden, um schlechten Code zu entschuldigen, und nach Möglichkeit vermieden werden sollten. Stattdessen sollte Ihr Code selbst lesbar und gut genug organisiert sein, damit ein anderer Entwickler ihn problemlos abrufen und mit der Arbeit beginnen kann.


"Einfacher zu folgen" ist tatsächlich eines der einfacher zu messenden und zu quantifizierenden Dinge. Sie können beispielsweise zufälligen Gruppen kompetenter Programmierer ein Codebeispiel präsentieren, das einen Fehler enthält, und angeben, wie lange sie brauchen, um ihn zu finden (Sie müssen jedoch zuerst eine Basislinie erstellen und beiden Gruppen einen Stapel identischen Codes präsentieren Dies ist umso wichtiger, wenn Ihre Gruppen klein sind oder Ihre Randomisierungsmethode möglicherweise nicht optimal ist. Andere Aufgaben können das Vorhersagen der Eingabe, das Bestimmen der algorithmischen Komplexität oder das Erraten der Funktionsweise des Codes (Multiple-Choice-Stil) umfassen.
tdammers

1
"Kommentare werden häufig verwendet, um schlechten Code zu entschuldigen, und sollten nach Möglichkeit vermieden werden", klingt für mich nach völligem Müll. Was er hätte sagen sollen ist: "Schlechter Code sollte nach Möglichkeit vermieden werden".
Sardathrion - gegen SE Missbrauch

1
@Sardathrion Er wird sagen zu schlechten Code zu vermeiden. In seinem gesamten Buch geht es darum, wie man das Schreiben von schlechtem Code vermeidet. Er sagt auch, um die übliche Praxis zu vermeiden, auf Kommentare zurückzugreifen, um schlechten Code zu maskieren, wenn man stattdessen besseren Code schreiben könnte.
Eric King

@EricKing: Ich habe das Buch nicht gelesen und kann daher nicht kommentieren, was der Autor tatsächlich gesagt hat. Die Zusammenfassung von Robert Greiner lautet jedoch wie folgt: " Kommentare werden verwendet, um fehlerhaften Code zu maskieren. Daher sollten Kommentare vermieden werden. " Ich glaube, das ist völliger Müll, wer auch immer es sagt. Das Verwenden von Kommentaren zum Maskieren von fehlerhaftem Code ist eine schlechte Praxis. Es ist eine schlechte Praxis, Ihren Code nicht zu kommentieren. Guter Code und gute Kommentare sind eine gute Praxis. ;> Robert Greiner: Könnten Sie klarstellen, was Sie meinten?
Sardathrion - gegen SE Missbrauch

1
@ Sardathrion du hast mich falsch zitiert. Früher habe ich genauso gedacht wie Sie, als ich mit dem Programmieren angefangen habe, und die Wahrheit ist, dass Kommentare nicht alles sind, was sie zu bieten haben. Ich empfehle Clean Code zu lesen, wenn Sie mehr über das Schreiben von großartigem Code erfahren möchten. Es hat wirklich dazu beigetragen, die Art und Weise zu gestalten, wie ich über Programmierung denke, und ich denke, es würde jedem, der es liest, helfen, ein besserer Programmierer zu werden.
Robert Greiner

7

Ich glaube, dass die Code-Formatierung einen großen Unterschied in der Lesbarkeit bewirken kann, aber meistens gut formatierter (oder sogar nur konsistent eingerückter) Code gibt mir ein warmes, verschwommenes Gefühl, dass der Autor tatsächlich ein wenig Sorgfalt walten ließ, anstatt nur zu schneiden. Einfügen aller Schnipsel, die er oder sie zur Hand hatte.

Bei Kommentaren bin ich mir nicht so sicher. Code, den ich schreibe, ich glaube fest daran, dass der Kommentar hilft. Wenn ich andererseits "Unternehmens" -Code verstehen möchte, auf den ich bei der Arbeit stoße, lösche ich gewöhnlich alle Kommentare, formatiere den Code neu, um eine konsistente Einrückung zu erhalten, und drucke ihn auf Papier aus, um ihn im Detail durchzulesen und grundlegende Blöcke zu markieren mit Bleistift usw.

Dieser Widerspruch (ich: gute Kommentare; alle anderen: irreführende Kommentare) lässt mich denken, dass Kommentare stark überbewertet sind. Sogar meine eigene.


1
Dies verdient eine +1 nur für den letzten Absatz allein :-)
Jörg W Mittag

Früher wünschte ich mir, unser letzter Programmierer hätte Kommentare verwendet. Dann habe ich den Teil seines Codes gefunden, in dem er Kommentare hinterlassen hat. Jetzt wünschte ich, unser letzter Programmierer hätte keine Kommentare verwendet.
Ben Brocka

6

Ja, der Kommentarstil beeinträchtigt die Lesbarkeit (wie kann das nicht?), Aber ich würde argumentieren, dass das von Ihnen angegebene Beispiel ein sehr schlechter Stil ist. Übermäßige Formatierung ist genau das: übermäßig.

Gute Kommentare zu schreiben ist eine Fähigkeit, die geübt und verfeinert werden muss, genau wie das Schreiben von Code.


2

IMHO ist der erste geeignet, um zu kommentieren, was eine Klasse tut oder am Anfang einer Quelldatei; Der zweite ist geeignet, um zu beschreiben, was der folgende Codeblock tut. für Methoden würde ich verwenden

//////////////////////////////////////////////////////////////////////
This code prints a basic "Hello world" message to the console screen. You can change the text in the brackets. 

Neben anderen großartigen Antworten denke ich, dass die Konsistenz im Kommentarstil ein weiterer Punkt ist. Wenn Sie verschiedene Arten von Kommentarstilen für dieselbe Art von Aufgaben verwenden, würde dies die Lesbarkeit Ihres Codes erheblich beeinträchtigen.


1

Das Beispiel, das Sie geben, ist etwas extrem, aber ja, Kommentare haben eine sehr wichtige Funktion.

Der Verfasser des Codes hat ein mentales Modell dessen, was er tun muss. Die Kommentare dienen dazu

  • dem Leser mitteilen, was dieses mentale Modell ist, und
  • Drücken Sie die Zuordnung zwischen dem mentalen Modell und der Implementierung durch den Code aus.

Auf diese Weise ist es bei Änderungen der Anforderungen wahrscheinlicher, dass die entsprechenden Änderungen am Code korrekt vorgenommen werden können, entweder vom ursprünglichen Autor oder von jedem, der später mitkommt.

Es ist auch gut zu versuchen, den Code so zu schreiben, dass er sich selbst erklärt, aber das ist selten 100% erfolgreich, daher sind die Kommentare notwendig.


0

Eine schnelle Antwort auf die Frage lautet „Ja“. Kommentare und Kommentarstil wirken sich eindeutig auf die Lesbarkeit und Verständlichkeit des Codes aus. Das ist die allgemeine Idee, aber die Qualität der Kommentarbeschreibungen und ihres Designs ist rein subjektiv.

Haben Sie jemals versucht, den Code und die Kommentare eines anderen zu lesen? Die meisten Programmierer schreiben Code und Kommentare basierend auf ihrem eigenen Stil und Wissensstand. Das Lesen ihrer Kommentare und ihres Codes ist wie der Versuch, sich in ihre Gedanken zu versetzen und ihren Praktiken zu folgen.

Eine Möglichkeit, dieses Problem zu vermeiden, besteht darin, einen grundlegenden „Prinzip- / Stilleitfaden“ zu verwenden, in dem die grundlegenden Richtlinien für Codestruktur, Zweck und Kommentare kurz beschrieben werden. Dieser Leitfaden muss von den Personen, die den Code schreiben, und allen anderen, die den Code möglicherweise lesen und möglicherweise erweitern, konsequent befolgt werden.


0

Stilistisch würde ich mit zwei Arten von Kommentaren gehen (für C ++ / Java)

/**
 * Multi-line comment
 */

oder

// Single-line comment

Eine IDE mit Syntaxhervorhebung reicht aus, um Ihre Aufmerksamkeit auf den Kommentar zu lenken. Sie müssen sich nicht mit der Formatierung auseinandersetzen.


0

Ja, der Kommentarstil beeinträchtigt sicherlich die Lesbarkeit. Jeder Kommentarstil, mit dem ich Kommentare schnell identifizieren kann, damit ich sie nicht lesen kann, hilft enorm, wenn ich wirklich versuche, den Code zu lesen .

Noch besser ist ein Code-Kommentarstil, mit dem ich die IDE verwenden kann, um die Kommentare direkt aus dem Blickfeld zu minimieren, sodass ich nicht die Energie aufwenden muss, um sie zu lesen.

Durch die Nutzung unserer Website bestätigen Sie, dass Sie unsere Cookie-Richtlinie und Datenschutzrichtlinie gelesen und verstanden haben.
Licensed under cc by-sa 3.0 with attribution required.