2. oder 3. Person Kommentare?

Question

Schreibst du Kommentare in der 2. oder 3. Person?

// go somewhere and do something (2nd person comment) 

oder

// goes somewhere and does something (3rd person comment) 

Answer 1

Definitiv 3. Person Stil.

Answer 2

Ich neige dazu, häufig Arzt Stil zu sprechen:

// Now we take $x and check whether it's valid for this pass 

Answer 3

Ein hilfreicher Tipp: versuchen Sie jeden Kommentar so zu halten wie möglich eigenständig. Zum Beispiel diese Form:

// First, mumble the frabbitz. 

blah blah 

// Second, foobar the quux 

blah blah 

dies ist eine schöne Erzählung, sondern macht es schwieriger, den Code zu bearbeiten, weil die „Ersten“ und „Zweiten“ Teile möglicherweise falsch worden. Am Ende fügen sie den Kommentaren nicht viel hinzu, sondern bringen sie in fragiler Weise miteinander in Beziehung.

Answer 4

Ich spreche manchmal in der 1. Person, wie diese

/* 
Usage: 
set_position(0.5, 0.5); // im in the center 
set_position(0.0, 1.0); // im in the lower,left corner 
*/ 

Answer 5

Es abhängen kann, wie viele Leute den Code bearbeiten und zu welchem ​​Zweck. In meinem eigenen Code (der dennoch öffentlich zugänglich ist) kann ich mich frei fühlen, einige persönliche Kommentare hinzuzufügen, vielleicht unter Verwendung von "Ich". In einem gemeinsamen Projekt sollten die Kommentare auf einen gemeinsamen Stil abzielen, und "ich" mag fehl am Platz sein.

Beachten Sie, dass Kommentare zerbrechlich sind und viele moderne Behörden (z. B. Clean Code) vorschlagen, dass Funktionen und Felder sinnvolle Namen tragen sollten. Aber natürlich gibt es viele Orte, an denen erklärende Kommentare noch wichtig sind.

Answer 6

Ich bin der Ansicht, dass Sie nur den Stil verwenden sollten, mit dem Sie sich am wohlsten fühlen.

Eingebettete Kommentare sollen von Ihnen und anderen Entwicklern gelesen werden, die versuchen, die Implementierungsdetails Ihres Codes zu verstehen. Solange sie klar und verständlich sind, ist es wichtig, ob sie etwas ungewöhnlich sind, die Grammatik ein wenig schlecht ist oder ein paar Rechtschreibfehler vorliegen. Die Leute, die es lesen, sollten sich nicht um solche Dinge kümmern.

Kommentare, die extrahiert werden, um API-Dokumentation zu erstellen, verdienen ein wenig mehr Aufmerksamkeit auf die Feinheiten von Stil, Grammatik und Rechtschreibung. Aber auch hier sind Genauigkeit und Vollständigkeit viel wichtiger.