[thelist] Basic Documentation Questions

Jason Lotito jason at clockmedia.com
Fri Feb 8 10:49:03 CST 2002


----- Original Message -----
From: "Jon" <jon at kickinsites.com>
Sent: Friday, February 08, 2002 11:24 AM
Subject: [thelist] Basic Documentation Questions
> [...snip...]
> -What types of things should be documented?
> -How does one go about documenting? (For example would one use comments
> within the code? A separate "documentation document"? Both? Other
> alternatives I haven't thought of?)
>
> I guess, in general I am looking for what are "good documenting
practices"?
>
> Thanks,
> Jon


As a PHP developer by profession, documentation is important.  Their are,
however, 2 types of documentation.

Inline and User.

Inline docs are also called 'comments'.  These, of course, are vital.
Comments allow developers to go back to their code months later with an
understanding of what they were thinking when they did something.  Comments
also allow new developers to pick up right were someone else left off.  It
also allows them to understand the code they now have to work with.

Inline comment structure is important, and I prefer the PHPDoc (which is
PHP's version of JavaDoc,
http://java.sun.com/j2se/javadoc/writingdoccomments/index.html) method of
commenting inline.  Also, PEAR uses PHPDoc, and puts it to good use.

PHPDoc information can be found here: http://www.phpdoc.de/index.html

Using this style of documentation, regardless of the language, can help
dramatically.  By forcing yourself to use this style, not only do you
subscribe to a standard, but you also standardize your code even more.

Sure, you can devise your own inline commenting style, the key is to remain
consistent.  For myself, PHPDoc does what I need it to do.

Other forms of internal documentation is line by line comments.

For example:

/* Make all our keys lowercase for consistency */
   $new_data = $this->keystolower($data);
   /* Loop through each transaction */
   foreach ( $new_data as $key => $transaction )
   {

Note: No, I don't comment every other line.

In the style above, you can pretty much grasp what we are doing at each
stage.  Commenting like this helps out tremendously in the long run.

However, Inline comments really should NOT be used for end user documents.
User docs in fact should be written outside the code.  When I talk about
User documents, I talk about the documentation for the intended user.  If
you are developing a class or a library, including your documentation
completely within your code is a bad idea.  Rather, create a documentation
paper or the like.  This way, someone can use your code without having to go
through all the code.

These types of User Docs are readily helpful, and are used all over the
place.

For example:

The C code for PHP contains comments, however, they are of no use to the
average PHP developer.  Rather, the PHP Manual is the User Doc, while the C
comments is for the PHP developers working with the C code.

You ask what should be documented?

As much as you think is necessary to properly express an idea.  If you
create a rather robust and highly complex piece of code, make sure its well
documented.  Go through exactly what is going on at each step.  I use a
simple rule of thumb: If I had to think about it, I comment it.  I know that
coming back to it later on, I will probably have to go through the same
process to figure what I was doing, so I save myself the trouble.

These are, though, just my comments. =)

Jason Lotito
Programmer & Developer
Clockmedia Inc.
Designing Tomorrow's Games, Today!
1-877-625-6256
514-908-2800
Fax: 514-908-2803





More information about the thelist mailing list