How complex is the documentation you write?

Question

In a book I'm reading there is a chapter on documentation for your code. The book is about PHP and described some easy methods but also going for some complicated and time consuming methods (xml, xsl) like DocBook.

At my current small company (5 people) we even rarely write comments, but I'm wondering if in a big company how detailed documentation do they write? Do they use such tools like DocBook? Is it complex or simple?

Answer 1

Working on PHP and NetBeans, the documentation style is pretty much PHPDoc way. Thus I write a little more than what the IDE generates.

e.g. IDE generates:

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

class ClassA{

    function __construct(){
        echo "5";
    }

}

I'll probably write:

/**  
 * 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

I follow this convention:

//-----------------------------------------------------------------------------
// 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);

I avoid adding author name as source control already take care of tracing original author and contributors.

Answer 3

I tend to write documentation like this:

Method name(method signature)

This is method. Here is a high-level explanation of what it does.

Here is what param 1 represents.

Here is what param 2 represents.

...etc.

Here is what it will do if you pass it invalid data in the parameters.

See also:

Method's class
Related method
Other related method

Answer 4

It depends on a few things:

• formalism of code. code that other people gets a finer comb than personal code
• technicality of code

As a rule, all non-trivial functions get a line that says what they do.

At the other end:

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

Plus a few delimiters such as /////////////////////////////////// or what-have-you.

Answer 5

I firmly believe that 90%+ of the time, code should be self documenting, IOW, variable names, method names and class names should clearly tell the story of what's happening. Only in rare cases when I'm having to do something somewhat unexpected (iterating through a collection and lowercasing the values) will I document WHY I'm doing it (not WHAT I'm doing).

I've got a roughly 500K line code base and I'd bet there are less than 30 lines of comments in the entire thing and it's (mostly) clear what the code is doing and why. I find I'm mostly documenting around external APIs.

Answer 6

Depends on the type of work you're doing, how it is run, with which SDLC approach and the size of the team.

In one group where I work, documentation is a wished for entity with variable names of 1-3 letters each. Half the time the class names are 1-3 letters each or a "handler." My own code is as much as possible self-documenting with about a 2-3 page word doc on how it should be used.

In the other group where I work it's a waterfall project. We write 30-40 pages worth of documents for each stage (this last document I wrote complete with diagrams, tables and figures was 60 pages.) There are 3 primary stages before code is even written and in each stage there is a specification, a preliminary, a checklist, a formal document, a verification matrix spreadsheet, and a review.

Hope that helps.