Schreiben Sie Titel in Codekommentare? [geschlossen]

Ich habe einen alten Code durchsucht, den ich geschrieben habe (erstes Jahr an der Universität), und festgestellt, dass ich Kommentartitel vor verschiedenen Teilen des Codes geschrieben habe. Sachen wie (das ist aus einem Monopoly-Spiel):

/*Board initialization*/
...code...

/*Player initialization*/
...code...

/*Game logic starts here*/
/*Displaying current situation*/
...code...

/*Executing move*/
...code...

/*Handle special event*/
...code...

/*Commit changes, switch to next player*/
...code...

Dies mag überflüssig und möglicherweise unnötig sein, wenn der Code wirklich sehr klar ist, aber als ich die Datei durchsuchte, war ich überrascht, wie stark ich das Gefühl hatte, zu wissen, was los ist, obwohl ich mich kaum mit dem eigentlichen Code befasst habe. Ich kann das definitiv als angemessen unter bestimmten Umständen ansehen, also frage ich mich - tun Sie das? Findest du das eine gute Idee? Oder ist es zu viel?

Dies ist ein Codegeruch. Das sagt was und nicht warum .

Wenn dies erforderlich ist, teilen Sie den Code in kleine Funktionen auf.

Das mache ich die ganze Zeit. Beides, um zu markieren, was der Code tut, und wahrscheinlich, wie Sie sagten, um das Scannen und Auffinden eines Codeblocks zu vereinfachen. Manchmal schreibe ich auch einen involvierten Prozess in Kommentare und 'fülle' den Code unter den Kommentaren aus, während ich gehe.

Ich finde es interessant, wie viele Menschen die Praxis nicht mögen, ohne wirklich artikulieren zu können, warum. Der Grund, warum Kommentare wie diese missbilligt werden, ist, dass sie ein Zeichen dafür sind, dass Sie gegen das Prinzip der alleinigen Verantwortung verstoßen haben. Dieser spezifische Name wird normalerweise nur in einem OO-Kontext verwendet, aber das allgemeine Konzept wird auch als Zusammenhalt bezeichnet und gilt für andere Paradigmen. In der Regel unterrichten Schulen solche Gestaltungsprinzipien erst gegen Ende eines Studiengangs, wenn überhaupt. Tatsächlich schreiben einige Lehrer die Verletzung vor, um die Bewertung zu vereinfachen, indem sie alles in eine Datei packen. Daher ist Ihre Unwissenheit als Neuling entschuldbar, und die Tatsache, dass Sie "etwas" falsch bemerkt und versucht haben, mit Kommentaren zu klären, ist unter den gegebenen Umständen sogar lobenswert. Im Allgemeinen ist es jedoch besser, ein unklares Design zu reparieren, als es mit Kommentaren zu überschreiben.

Ich betrachte diese Dinge als eine Möglichkeit, den Code klarer zu machen oder nicht. Wenn Sie auf die Methoden in der Datei tell basieren kann , was jeder Teil besteht dann besteht keine Notwendigkeit , aber wenn Sie haben mehrere Abschnitte haben , dann kann es nützlich sein. Wenn eine Codedatei zu groß wird, muss sie möglicherweise aufgelöst werden, was die Notwendigkeit solcher Kommentare verringert.

Ich würde sagen, wenn Sie in einem Team arbeiten, um einen Standard zu entwickeln, codieren und kommentieren Sie zumindest alle auf die gleiche Weise, damit das Betrachten des Codes einfacher wird.

Ich mache das, weil ich oft meine Absicht mit mir selbst kommuniziere oder im Grunde genommen ein Lesezeichen für Dinge wie "Datenbereinigung beginnt hier" einsetze. Normalerweise wird unter diesem Titel ein kurzer Einblick in die Logik dessen gegeben, was ich mache und warum.

Ich mag Redundanz. Wenn ich mein Laborheft aus dem einen oder anderen Grund verliere oder den Code, den ich vor Jahren geschrieben habe, erneut lesen muss, mag ich es nicht, zusammenzufügen, was ich getan habe und warum ich es getan habe. Wenn zumindest ein Teil dieser Logik im Code enthalten ist, ist sie dokumentiert genug, damit ich zumindest wieder damit arbeiten kann.

Ich denke, ein Teil meiner Neigung dazu ist statistisch und daher etwas repetitiv. Während es einige Codeteile gibt, in denen ich nach einer hilfreichen Funktion mit Namen suchen muss, kann ich einige Dutzend ziemlich ähnliche Verwendungen einer allgemeinen linearen Modellfunktion haben. Es ist nützlich, in der Lage zu sein, herauszufinden, welcher der Codes "Wie empfindlich sind die Ergebnisse für den Code" Choice A vs. Das wird oft durch Titel beschleunigt.

Ich denke, dass dies in Situationen nützlich ist, in denen Sie gigantische Quelldateien mit Dutzenden von Funktionen haben und diese locker in solche Abschnitte organisieren können. Ich sage nicht, dass mir das besser gefällt als kleinere, fokussiertere Quelldateien ...