Kommentierungs- / In-Code-Dokumentationsstile

Das mag eine dumme Frage sein, aber sie ist schon eine Weile in meinem Hinterkopf und ich kann nirgendwo anders eine anständige Antwort finden.

Ich habe einen Lehrer, der sagt, wir sollten jeden Parameter explizit mit einer Beschreibung auflisten, auch wenn es nur einen gibt. Dies führt zu vielen Wiederholungen:

double MyFunction(const int MyParam);
// Function: MyFunction
// Summary: Does stuff with MyParam.
// Input: int MyParam - The number to do stuff with.
// Output: MyParam with stuff done to it.

Wie detailliert sind Sie beim Schreiben von In-Code-Dokumentationen?

Für den Anfang stimme ich zu, dass die Zeile "Function:" in Ihrem Beispiel vollständig redundant ist. Ich habe auch die Erfahrung gemacht, dass die Leute in der Schule gelernt haben, diese Art von Kommentaren hinzuzufügen, und diese Art von Kommentaren weiterhin in ihren Produktionscode aufgenommen haben.

Gute Kommentare wiederholen nicht, was im Code steht. Sie beantworten die Frage "Warum?" anstelle von "Was?" oder wie?" Sie decken die Erwartungen an die Eingaben sowie das Verhalten des Codes unter bestimmten Bedingungen ab. Sie behandeln, warum Algorithmus X anstelle von Algorithmus Y gewählt wurde. Kurz gesagt, genau die Dinge, die für jemand anderen ¹ beim Lesen des Codes nicht offensichtlich wären .

^{1: Jemand anderes, der mit der Sprache vertraut ist, in der der Code geschrieben ist. Schreiben Sie keine Kommentare, um zu unterrichten, sondern Kommentare, um Informationen zu ergänzen.}

Einige Sprachen verfügen über Funktionen zur Generierung von API-Dokumenten wie Ruby, Java, C # und C ++ (über ein Befehlszeilentool). Wenn Sie so darüber nachdenken, wird das Schreiben der API-Dokumente viel wichtiger. Immerhin beantwortet es die Frage "Wie mache ich ...?" Ich werde also nichts wiederholen, Function: MyFunctionwenn der Name der Funktion für alle sichtbar ist. Die Tools zur Generierung von API-Dokumenten sind intelligent genug, um dies für mich zu tun. Die folgenden Details sind jedoch nützlich, insbesondere bei öffentlichen Methoden / Funktionen:

• Zusammenfassung (was es tut und wenn relevant eine Zusammenfassung der Verwendung)
• Liste der Parameter und was erwartet wird
• Wie hoch ist der Rückgabewert (Ausgabe)?
• Alle Ausnahmen, die explizit ausgelöst werden können und warum

Diese können nützliche Referenzwerkzeuge werden, wenn Sie versuchen, Code zu debuggen. Viele IDEs verwenden die API-Dokumente auch in ihren QuickInfos, wenn Sie mit der Maus über den Funktionsnamen fahren.

Wenn es sich um eine Sprache ohne diese Funktionen handelt, helfen die Kommentare, aber bei weitem nicht so viel.

Wenn es sich um eine öffentliche API-Methode handelt, sollten Sie eine detaillierte Dokumentation bereitstellen, insbesondere zu Parametern und erwartetem Verhalten. Viele Menschen glauben, dass dies für private Methoden / Funktionen, YMMV, gelockert werden kann.

Insgesamt bevorzuge ich es, sauberen Code (kleine Methoden / Funktionen, die eine Sache und eine Sache gut machen) mit vernünftigen Variablennamen zu schreiben. Dies macht einen Großteil Ihres Codes selbstdokumentierend. Ich dokumentiere jedoch auf jeden Fall immer alle Randfälle, die Verwendung von Parallelität und komplexe Algorithmen.

Kurz gesagt, denken Sie an sich selbst in 3 Monaten um 3 Uhr morgens etwas schlechter. Sie werden sich für Ihre großartigen öffentlichen Dokumente bedanken, anstatt herauszufinden, was Parameter (Boolesches Flag) bedeuten ...

Dies ähnelt der Analyse der In-Code-Dokumentation durch die meisten -Doc-Frameworks (JavaDoc, PHPDoc usw.).

Von Java, automatisch von IDE generiert:

/**
 * [Description]
 * @param str [Description]
 * @param isCondition [Description]
 * @return [Description]
 */
public int testFunction(String str, boolean isCondition) {
    ...
}

Dies ist das gleiche Format, das zum Generieren der Dokumentation für die integrierten Sprachfunktionen verwendet wird. Beispiel: http://download.oracle.com/javase/6/docs/api/java/lang/String.html

Dieses Format ist sehr hilfreich, da es jedem Drittbenutzer klar zeigt, wie er mit Ihrem Code umgeht. Wenn Ihre Funktionen private Methoden sind, die nur intern verwendet werden, kann dies ein wenig sinnlos sein - aber ich würde vermuten, dass Ihr Lehrer versucht, Sie in eine gute Praxis zu bringen, bis Sie alle Erfahrung mit dieser Unterscheidung haben.

Das einzige Bit, das ich oft als etwas überflüssig empfinde, ist die Rückgabebeschreibung - normalerweise ist sie fast identisch mit meiner Methodenbeschreibung.

Es gibt zwei Zwecke für Kommentare:

1. Sie dienen dazu, Sie schnell daran zu erinnern, was Ihr Code tut, wenn Sie Monate / Jahre später darauf zurückkommen. Auf diese Weise müssen Sie Ihren Code nicht erneut lesen und analysieren, um Ihr Gedächtnis aufzufrischen.
2. Sie geben an andere Personen weiter, die möglicherweise Ihren Code lesen oder damit arbeiten, was Ihr Code tut.

Es gibt natürlich viele verschiedene Möglichkeiten, dies zu erreichen, aber je gründlicher und konsequenter Sie sind, desto besser. Effektives Kommentieren braucht Zeit, um zu lernen, genau wie effektives Programmieren. Denken Sie daran, dass es schwierig ist, den Sinn von Kommentaren in der Schule zu erkennen, da nichts, an dem Sie arbeiten, jemals groß genug ist, um es wirklich zu rechtfertigen, aber sie versuchen nur, es Ihnen vorzustellen. Und normalerweise ist die Art und Weise, wie Sie es lehren, der Stil Ihres Professors, keineswegs irgendein Standard. Entwickeln Sie, was für Sie funktioniert. Und denk dran ... es gibt so etwas wie einen dummen Kommentar! :) Beispiel:

a += 1; //adds 1 to the value in a

"Ja wirklich?" Vielen Dank! LOL

Ich mag die Dokumentation von der PHP-Website, daher verwende ich etwas Ähnliches für meine Inline-Kommentare und verwende die PHPDoc-Syntax. Siehe das folgende Beispiel.

/*
* Finds all the locations where you have access to for this client and returns them in an array .
* @author Radu
* @version 1.0
* @param int $id ( The id of the client for which you're requesting access. )
* @param object $db ( A resource of type Mysql, representing a connection to mysql database, if not supplied the function will connect itself. )
* @return array ( Returns array with id's of locations that you are allowed to see, an empty array if you do not have acces to any locations or returns FALSE and triggers a Warning if any error occuread )
* @use array allowed_locations ( $id [, $db] )
*/
function allowed_locations($id, $db=NULL){ ... }

Und wie @ Larry Coleman sagte, sollten Inline-Kommentare erklären, warum Sie einen Teil des Codes erstellt haben.

$funcResult = SomeFunction();
if(is_array($funcResult))
{    //Beacause SomeFunction() could return NULL, and count(NULL) = 1
    $c = count($funcResult);
} else {
    $c = 0;
}
if($c == 1)
{
 ... 
}else
{
 ...
}

Wenn es im Dienst der Doc-Generierung steht, sind ausführliche Kommentare (obwohl irritierend) wahrscheinlich eine gute Sache. Obwohl Sie es sich zum Teamziel machen müssen, den Überblick über Kommentare zu behalten und diese auf dem neuesten Stand zu halten.

Wenn es nur der Kommentarstil ist, hätte ich Probleme damit. Übermäßige Kommentare können den Code genauso verletzen wie helfen. Ich kann nicht zählen, wie oft ich auf Kommentare im Code gestoßen bin, die veraltet und daher irreführend waren. Normalerweise ignoriere ich jetzt Kommentare und konzentriere mich darauf, den Code und die Tests des Codes zu lesen, um zu verstehen, was er tut und was die Absicht ist.

Ich hätte lieber einen klaren, prägnanten, nicht kommentierten Code. Geben Sie mir einige Tests mit beschreibenden Aussagen oder Methoden und ich bin glücklich und informiert.