Code-Dokumentation: Wie viel ist zu viel?

Question

Wie viel Code-Dokumentation in Ihre .NET-Quelle ist zu viel?

Einige Hintergrundinformationen: Ich geerbt eine große Code-Basis, die ich habe in einigen der anderen Fragen sprach über die ich hier auf SO gepostet habe. Einer der „Features“ dieser Code-Basis ist ein Gott der Klasse, eine einzige statische Klasse mit> 3000 Zeilen Code mehrere Dutzend statische Methoden umfasst. Es ist alles von Utilities.CalculateFYBasedOnMonth() bis Utilities.GetSharePointUserInfo() Utilities.IsUserIE6(). Es ist alles gut Code, der muss nicht neu geschrieben werden, nur in ein Refactoring entsprechender Satz von Bibliotheken. Ich habe, dass geplant.

Da diese Verfahren in eine neue Business-Schicht bewegen, und meine Rolle in diesem Projekt ist das System für die Wartung von anderen Entwicklern zu bereiten, ich denke an fester Code-Dokumentation. Während diese Verfahren alle guten Inline-Kommentare haben, tun sie alle haben nicht gut (oder jede) Code doco in Form von XML-Kommentare. Mit Hilfe einer Kombination aus GhostDoc und Sandcastle (oder Document X), kann ich ein paar ziemlich nette HTML-Dokumentation erstellen und per Post an Sharepoint, die Entwickler mehr über verstehen lassen würde, was der Code tut, ohne sich durch den Code zu navigieren.

Da die Menge an Dokumentation in dem Code zunimmt, wird desto schwieriger wird es, den Code zu navigieren. Ich fange an, wenn die XML-Kommentare als zur Aufrechterhaltung der Code schwieriger machen zu fragen, sagen wir, ein einfacheres //comment würde auf jedem Verfahren.

Diese Beispiele sind aus dem Dokument X Probe :

        /// <summary>
        /// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
        /// </summary>
        /// <returns>A new Customer instance that represents the new customer.</returns>
        /// <example>
        ///     The following example demonstrates adding a new customer to the customers
        ///     collection. 
        ///     <code lang="CS" title="Example">
        /// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
        ///     </code>
        ///     <code lang="VB" title="Example">
        /// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
        ///     </code>
        /// </example>
        /// <seealso cref="Remove">Remove Method</seealso>
        /// <param name="Title">The customers title.</param>
        /// <param name="FirstName">The customers first name.</param>
        /// <param name="MiddleInitial">The customers middle initial.</param>
        /// <param name="LastName">The customers last name.</param>
        public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
        {
            // create new customer instance
            Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);

            // add to internal collection
            mItems.Add(newCust);

            // return ref to new customer instance
            return newCust;
        }

Und:

    /// <summary>
    /// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
    /// </summary>
    /// <value>
    /// An Int value that specifies the number of Customer instances within the
    /// collection.
    /// </value>
    public int Count
    {
        get 
        {
            return mItems.Count;
        }
    }

Also ich frage mich, von Ihnen: dokumentieren Sie alle Ihres Codes mit XML-Kommentare mit dem Ziel, so etwas wie NDoc (RIP) mit oder Sandburg? Wenn nicht, wie Sie entscheiden, welche Unterlagen bekommt und was nicht? So etwas wie eine API wäre natürlich doco, aber was ist mit einer Code-Basis, die Sie gehen zu einem anderen Team zu übergeben halten?

Was denken Sie, ich tun sollte?

Answer 1

Ich denke, ein guter Teil des Problems ist hier die ausführliche und crufty XML-Dokumentation Syntax MS auf uns aufgedrängt hat (JavaDoc war nicht viel besser). Die Frage, wie es zu formatieren ist, zu einem großen Teil, unabhängig davon, wie viel ist angemessen.

Mit dem XML-Format für Kommentare ist optional. Sie können Doxygen oder andere Werkzeuge verwenden, die verschiedene Formate zu erkennen. Oder Ihr eigenes Dokument Extraktor schreiben -. Es ist nicht so schwer, wie Sie vielleicht denken, eine angemessene Arbeit zu tun und ist eine gute Lernerfahrung

Die Frage, wie viel schwieriger ist. Ich denke, die Idee des selbsterklärend Code ist in Ordnung, wenn Sie in graben einen Code zu erhalten. Wenn Sie nur ein Kunde sind, sollten Sie nicht brauchen, um den Code zu lesen, zu verstehen, wie eine bestimmte Funktion funktioniert. Viele Informationen ist implizit in den Datentypen und Namen, natürlich, aber es gibt sehr viel, das nicht der Fall ist. Zum Beispiel auf ein Objekt in einer Referenz vorbei sagen Ihnen, was zu erwarten ist, aber nicht, wie eine Nullreferenz wird behandelt werden. Oder in dem Code des OP, wie jeder Leerzeichen am Anfang oder am Ende der Argumente behandelt werden. Ich glaube, es ist far mehr von dieser Art von Informationen, die dokumentiert werden sollen, als man in der Regel anerkannt.

Für mich erfordert es natürliche Sprache Dokumentation den Zweck der Funktion sowie alle Pre- und Post-Bedingungen für die Funktion, ihre Argumente zu beschreiben, und Rückgabewerte , die nicht durch die Programmiersprache ausgedrückt wird Syntax .

Answer 2

Niemand erwähnt Ihr Code nicht aufgebläht zu sein braucht, die XML-Dokumentation in einer anderen Datei sein kann:

/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>

Und dann Add-Methode keine zusätzlichen XML / Kommentare darüber enthalten kann, oder wenn Sie nur die Zusammenfassung bevorzugen (wie die mit der separaten Datei zusammengeführt wird).

Es ist viel mächtiger als das Müll-Format, das Javadoc ist und derivaten Sie in PHP / Javascript finden (obwohl Javadoc den Weg für die XML-Syntax gepflastert). Plus die verfügbaren Werkzeuge sind weit überlegen und der Standard-Look der Hilfe docs ist besser lesbar und einfacher zu gestalten (ich kann sagen, dass aus geschrieben Doclets hat und zu vergleichen, diesen Prozess zu Sandcastle / DocProject / NDoc).

Answer 3

Sie schlagen eine kritische Kluft hier zwischen denen, die die neuen Bibliotheken und diejenigen beibehalten werden, die die neuen Bibliotheken raubend werden.

Wenn ich eine neue Anwendung zu schreiben und wird diese Standardbibliotheken verwenden, sollte ich eine stabile binäre der Bibliotheken bekommen und sie einfach in meine Anwendung zu importieren, nicht den Quellcode Kopieren nach unten von einem Ort und möglicherweise Probleme verursachen wenn der Code wird geändert. In diesem Fall muss ich keinen Zugriff auf die „Selbst Dokumentieren“ Features, die andere als der Name des Verfahrens und die Ein- / Ausgabeparameter, und selbst diejenigen nicht ausgesetzt werden, wenn ich irgendeine Art von IDE bin mit das muss nicht das auto komplett funktionseingeschaltet.

Also in Ihrem Beispielcode oben, ich denke, es ganz gut aussieht. Die Dinge sind nicht zu ausführlich im Code selbst und die Namen sind selbstdokumentiere. Auf der anderen Seite, alle notwendigen Zusammenfassung / Parameterdaten ist es so, dass eine solide Dokumentation Stück alle wichtigen Informationen zur Hand zu haben, diejenigen raubend, die Bibliothek aufgebaut sein könnte zu ermöglichen. Leider XML ist ziemlich aufgebläht, aber in großen denke ich, die meisten Entwickler leicht rechts von alle Zusammenfassung Inhalt blättern und schauen Sie in den eigentlichen Code innerhalb der Methode.

Answer 4

Jeff einen wirklich guten Artikel über Kommentierung hat (oder soll ich sagen, Kommentierung nicht) hier ...

http://www.codinghorror.com/blog/archives/001150.html

Ich weiß, es scheint, als ob ich nicht die Frage zu beantworten, aber ich denke, es ist ein gültiger Punkt ist, dass Code sollte so selbsterklärend wie möglich sein.

Answer 5

Ich neige dazu, alle öffentlichen Methoden in meinem eigenen Code zu dokumentieren; GhostDoc Verwendung macht dies trivial. Und um die Unordnung zu reduzieren, wenn ich meinen Quellcode bearbeiten, ich in der Regel nur die Kommentare zusammenbrechen, indem man zuerst in „outline-Modus“ gehen (das heißt Visual Studio Gliederung verwenden> Zusammenbruch Definitionen Befehl).

Ich habe nie versucht, Sandburg, aber ich wirklich zu schätzen den Komfort von Intellisense für die Methoden zur Verfügung gestellt habe ich XML-kommentiert.

Answer 6

ich immer entscheiden sich für die XML / Javadoc-Format Kommentare, weil ich in der Lage, Liebe API-Dokumentation in einem vernünftigen Format (HTML in der Regel) zu sehen.

Es ist zu einem Problem geworden, die eigentliche Quellcode für das Surfen, aber ich finde, dass dies in der Regel ein kleines Problem, da Visual Studio zu kollabieren XML-Kommentare wie nötig im Allgemeinen ziemlich klug ist.

Answer 7

Sie sich nicht wiederholen.

• Das erste Beispiel sollte eine bessere Methode Namen haben und überhaupt keine Kommentare.
• Das zweite Beispiel sollte keinen Kommentar haben.

Der Name des ersten Verfahrens sollte widerspiegelt, dass ein neues Objekt zugeordnet ist.

Wenn das Verhalten im gesamten Rahmen Standard ist für jedes Add, sollte es auf einer höheren Ebene zu dokumentieren, die nicht in dieser Methode API doc. Andernfalls den Namen ändern.

Kommentare sollten Informationen hinzufügen, verbirgt es nicht in Lärm. Und es sollte Kommentare, bei Bedarf in XML. Und wo sie einen Mehrwert.

Ich will nicht, um zu sehen: „Gibt die Anzahl“ für eine Methode mit dem Namen zählen.

Answer 8

Alle öffentlichen Funktionen müssen von jemandem klar verständlich sein, der eine flüchtige Bekanntschaft mit dem Code-Basis hat, aber nicht in Ihrem speziellen Abschnitt, ohne tauchen Sie ein in den Code.

Wenn Sie eine kurze Linie zu schreiben, zu erklären, was eine Funktion hat, stehen die Chancen Sie Ihre Funktion / Klassen schlecht benannt. Der Name sollte selbsterklärend in diesem Fall sein

Wenn es mehr als 1 kurzen Satz zu erklären, erfordert, das ist wahrscheinlich ein guter Kommentar

Wenn es einen Absatz, Ihre Funktion wahrscheinlich zu viel tut, außer wahrscheinlich unklar Namen.

Es ist in der Regel besser auf der Seite der Kommentare irren WENN SIE MACHEN, DASS SIE GENAU . Ungenaue und / oder wartbaren Kommentare sind schlimmer als keine Kommentare

So Anwendung dieser Regeln:

Im ersten Beispiel: „// neue Kunden Instanz erstellen“ ist überflüssig. Der Code ist kristallklar. Die anderen Kommentare sind perfekt. Sie klären, was der Code arbeitet auf /, was es resuls sind

In Ihrem zweiten Beispiel die Kommentare Mühe verschwendet und machen es schwer zu lesen. Alles was Sie tun müssen, ist die Funktion einen richtigen Namen zu geben. Nicht, dass vage „zählen“. Das ist eine schlechte Namensgebung.

Answer 9

Ich leitete vor kurzem eine Studie, die das zeigt, wenn Sie wichtige „Richtlinien‚haben zB Caller X‘in einer Menge von Spezifikationen (zB‚tun muss diese Methode nicht X, was bedeutet, Y und Z‘), gibt es eine sehr hohe Risiko, dass Ihre Leser die Richtlinien vermissen würden. In der Tat, wenn sie eine lange Dokumentation, überspringen sie es alltogether zu lesen.

So zumindest, trennen Sie die wichtigen Sachen oder benutzen (fragen Sie mich, wenn Sie Java verwenden) Tagging.

Answer 10

Alles auf den Standards hängt Ihr Unternehmen verwendet, aber für meine Mannschaft, dokumentieren wir an der Spitze jeder Funktion wie in Ihrem zweiten Beispiel (die durch die Art und Weise Sie in Visual Studio 2008 durch das Drücken der „/“ tun können Taste 3 mal hintereinander an der Spitze jeder Unter oder Funktion !!).

Das erste Beispiel ist übertrieben, vor allem die unteren paar Zeilen, in denen jede Zeile kommentiert wird. Aber ich denke, das Zeug in der Kopfzeile der Funktion zwar nützlich sein könnte, weil wir es hier eine Menge zu verwenden. Und es scheint etwas Standard zu sein von dem, was ich von vielen anderen Programmierern berichten.

Answer 11

Ich habe Standards gesehen Codierung, die gegen Kommentierung selbst zu kommentieren Code und Verfahren Überlastungen empfehlen. Während YMMV, es wie ein guter Weg, klingt aus den wegzukommen „Feld _numberOfCars eine ganze Zahl, die die Anzahl von Autos darstellt“ -Typ Kommentare, die in viel des Guten führen.

Answer 12

Kommentare in einem Header für die Dokumentation zu erzeugen ist eine gute Sache. Putting Kommentare in Code zu erklären, warum Sie das tun, was Sie tun, ist auch in der Regel eine gute Sache. Putting in redundanten Kommentare zu paraphrasieren, was Sie getan haben, ist keine gute Sache

Answer 13

Was Sie haben, ist viel zu viel gezeigt. Haben Sie sich selbst einen Gefallen und löschen Sie es!

Der Code sollte zunächst einmal selbstdokumentiere sein, durch sinnvolle Methode und Parameternamen. Im Beispiel haben Sie gezeigt;

Öffentliche Kunden Add (Titel, string Vorname, string Middle, string Name) ist durchaus verständlich, auf die Absicht das, was geschieht, wie es ist ‚Count‘.

wie dieses zu kommentieren, wie Sie wies darauf hin, rein ist Rauschen um, was ist sonst einfach Code zu lesen. Die meisten Entwickler werden früher nach oben öffnen und prüfen Sie den Code verwenden, als Stapel durch obskure automatisch generierte API-Dokumentation. Jedes Mal!

Answer 14

Durch die Art und Weise, nach „Clean Code“ (Ein großes Buch, BTW), sollte man vermeiden, mit HTML / XML-Markups innerhalb von Kommentaren, die im Quellcode eingebettet sind. Selbst wenn Ihre IDE raffinierte Dokumentation erstellen können, wenn Sie schweben, ist es zu sehr stört und nicht lesbar betrachtet, wenn Sie nur Ihre Quellen suchen.