Hat der Kommentarstil Einfluss darauf, wie Leser Code verstehen?

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?

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.

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.

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.

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.

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.

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.

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.

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.