Wie komplex ist die Dokumentation, die Sie schreiben? [abgeschlossen

Question

In einem Buch, das ich lese, gibt es ein Kapitel über Dokumentation für Ihren Code. Im Buch handelt es sich um PHP und beschrieben einige einfache Methoden, aber auch einige komplizierte und zeitaufwändige Methoden (XML, XSL) wie Docbook.

Bei meiner aktuellen kleinen Firma (5 Personen) schreiben wir sogar selten Kommentare, aber ich frage mich, ob in einer großen Firma, wie detaillierte Dokumentation schreiben, in einem großen Unternehmen schreiben? Verwenden sie solche Tools wie Docbook? Ist es komplex oder einfach?

Answer 1

Der Dokumentationsstil, der an PHP und NetBeans arbeitet, ist so ziemlich phpdoc ay. So schreibe ich ein wenig mehr als das, was die IDE erzeugt.

zB ide erzeugt:

/**  
 * Description for ClassA  
 *  
 *  
 * @author Sam-Mauris Yong  
 */  

class ClassA{

    function __construct(){
        echo "5";
    }

}

Ich werde wahrscheinlich schreiben:

/**  
 * Class A Helper Class
 * Some example class used here
 *  
 * @author Sam-Mauris Yong
 * @license GNU Public License v3
 */  

class ClassA{

    /**
     * Constructor for example class
     * echos 5
     */
    function __construct(){
        echo "5";
    }

}

Answer 2

Ich folge dieser Konvention:

//-----------------------------------------------------------------------------
// MPlayer_PlayAlbum
//
// PURPOSE:
//  Creates a playback selection of the given album and starts playing it
//
// PARAMETERS:
//  int AlbumId  [in] Zero based index of the album to playback,
//                    or -1 to playback all the albums (not for iPod)
//  int ArtistId [in] Zero based ID of the artist, or -1 if AlbumId is from the
//                    global enumeration of albums; if AlbumId is -1 this
//                    parameter is ignored
//  int TrackId  [in] Zero based index of the track representing the first item
//                    to play; if AlbumId is -1 this parameter is ignored
//
// RETURNS:
//  ERROR_SUCCESS if the function succeeds
//  ERROR_UNINITIALIZED if the remote control is not initialized
//  ERROR_INVALID_PARAMETER if one ore more parameters are not correct
//  ERROR_DEVICE_NOT_AVAILABLE if no device is present
//  ERROR_DEVICE_IN_USE if it's currently impossible to use the device remotely
//-----------------------------------------------------------------------------
DWORD WINAPI MPlayer_PlayAlbum(int AlbumId, int ArtistId, int TrackId);

Ich vermeide es, Autorennamen als Quellenkontrolle hinzuzufügen, die sich bereits um die Verfolgung des ursprünglichen Autors und der Mitwirkenden kümmern.

Answer 3

Ich neige dazu, eine solche Dokumentation zu schreiben:

Method name(method signature)

Das ist method. Hier ist eine hochrangige Erklärung dessen, was es tut.

Hier ist, was Param 1 darstellt.

Hier ist, was Param 2 darstellt.

...etc.

Hier ist, was es tun wird, wenn Sie es in den Parametern ungültige Daten übergeben.

Siehe auch:

Method's class
Related method
Other related method

Answer 4

Es hängt von einigen Dingen ab:

• Formalismus des Kodex. Code, dass andere Leute einen feineren Kamm als persönlichen Code erhalten
• Technik des Codes

In der Regel erhalten alle nicht trivialen Funktionen eine Zeile, die sagt, was sie tun.

Am anderen Ende:

//funcname
//purpose
//params and their meaning
//description incl. weirdnesses
//exceptions that might show up
//maintainer notes
//future todos

Plus ein paar Abgrenzer wie /////////////////////////////////// oder was have-you.

Answer 5

Ich bin fest davon überzeugt, dass Code von 90%+ der Zeit selbst dokumentiert werden sollte, IOW, Variablennamen, Methodamen und Klassennamen die Geschichte klar, was passiert. Nur in seltenen Fällen, in denen ich etwas Unerwartetes tun muss (Iterte durch eine Sammlung und die niedrigere Werte), werde ich dokumentieren, warum ich es mache (nicht das, was ich tue).

Ich habe eine rund 500.000 Zeilencode -Basis und ich wette, es gibt weniger als 30 Kommentare in der gesamten Sache und es ist (meistens) klar, was der Code tut und warum. Ich finde, ich dokumentiere hauptsächlich um externe APIs.

Answer 6

Hängt von der Art der Arbeit ab, die Sie ausführen, wie es ausgeführt wird, mit welcher SDLC -Annäherung und der Größe des Teams.

In einer Gruppe, in der ich arbeite, ist die Dokumentation für Entität mit jeweils variablen Namen von 1-3 Buchstaben gewünscht. Die Hälfte der Zeit sind die Klassennamen jeweils 1-3 Buchstaben oder "Handler". Mein eigener Code ist so viel wie möglich mit einem 2-3-seitigen Word-Dokument, wie er verwendet werden soll.

In der anderen Gruppe, in der ich arbeite, ist es ein Wasserfallprojekt. Wir schreiben Dokumente im Wert von 30-40 Seiten für jede Phase (dieses letzte Dokument, das ich mit Diagrammen, Tabellen und Zahlen geschrieben habe, betrug 60 Seiten.) Es gibt 3 Primärstadien, bevor der Code sogar geschrieben wird, und in jeder Phase gibt es eine Spezifikation, a Vorläufigkeit, eine Checkliste, ein formales Dokument, eine Überprüfungsmatrix -Tabelle und eine Überprüfung.

Ich hoffe, das hilft.