Sujith Nair
Many of you would agree with me when I say that programming is an art. Logic of course is an essential part, but so is the manner in which the whole code is written. I strongly believe that a programmer should not ignore this aspect of documentation of code. For php programmers there is always PEAR that gives you guidelines on "How to's" regarding php programs and packages.
Perhaps the most important part of the PEAR project is finally defining an official standard for creating reusable, well-documented php packages. Since PEAR is still under development, there are many more important guidelines yet to follow.
So, why do we really need to document our code? Answer to this question may differ from programmer to programmer. But I strongly feel, it helps in Debugging, Reverse Engineering, Re-engineering, Testing and giving the code a neat look. Moreover, it's a step towards standardization of coding methodology. It's a common tendency among programmers to make their code so scary that the other programmer would never dare to understand it ;-)
But a good programmer is one who makes his code look so simple and comprehensible that any other programmer can understand it and appreciate it. The program should be such that even in your absence any other authenticated person can go through the well-documented code and make productive changes. This is good for yourself and the organisation as well. Gone are the days when there were closed codes and environments. Now, only those products will survive which have scope of improvement and have the flexibility to perform in ever demanding conditions.
I would like to discuss with you certain aspects of documentation.
Block Comments
Comments form an important part in documentation. You can start the program with a brief description of the entire program on top of the page. Here is how you can do this:

<?php

/***********************************************************
* Class to populate the <select> form field from mysql table
* This class enables you to populate a select form field with
* option lists from any database.
* Made By Sujith Nair [sujith_77@hotmail.com]
* On September 14, 2001
************************************************************/

class populate_sel {


var 
$hname="<hostname>";
var 
$uname="<username>";
var 
$pname="<password>";
var 
$dbname="<database name>";
var 
$tname;
var 
$fname;
var 
$sel;

// And the code follows
?>
The first few lines gives a brief description of the class. This is how I prefer to display a block of description.
Line comments
Line comments can be used to explain any particular action in the code. This is demonstrated below.

<?php

function populate_sel($t_name,$f_name,$sel=""// Constructor to initialize relevant values.
{
    
$this->tname=$t_name;
    
$this->fname=$f_name;
    
$this->sel=$sel;
}
// And the code follows
?>
I prefer to place the Line Comment on the same line with the particular action, rather than placing it above or below the action. The Following is what I don't prefer:

<?php

// Constructor to initialize relevant values.
function populate_sel($t_name,$f_name,$sel="")
{
    
$this->tname=$t_name;
    
$this->fname=$f_name;
    
$this->sel=$sel;
}
// And the code follows
?>
Indenting
The code should be properly indented so that the control structures are visible and can be properly understood. The PEAR RFC standard recommends four spaces, not tabs of any size, in your code. But you can use spaces for the same. Here is an example of indenting code.

<?php

function foo()
{

while(
c){

if(
a==b){
    if(
b==c){
        
// code follows
            
}
        else{
            
// code follows
                
}
        }
        else{
            
// code follows
            
}

    }

    
// code follows

}
// And the code follows
?>
I prefer opening parenthesis to follow the conditions in control structures, but the opening parenthesis should start with the new line in case of functions or classes or class members. Also the IF and ELSE statements should be well covered by braces.
Opening and closing tags
It is always recommended that PHP code should be enclosed within <?php and ?> tags. Though, <? and ?> or <% and %> can be used but they might in some cases conflict with ASP or XML tags.
Others
Care should be taken that proper comments should be added in the code regarding all includes (include files). Their role and importance should be carefully explained. We should also ensure that the principle of modularity in programs is followed. Modularity helps when we are forced to make necessary changes in the code due to some additions or as per the recommendations of the tester or QA.
Moreover, in case of white box testing a proper coding standard is always helpful. For those who are not conversant with the various testing techniques, i would like to explain that White-box testing strategies include designing tests such that every line of source code is executed at least once, or requiring every function to be individually tested. Very few white-box tests can be done without modifying the program, changing values to force different execution paths, or to generate a full range of inputs to test a particular function. Thus as a part of the SDLC we can't afford to ignore the other aspects of SDLC as well, like, designing, testing, maintenance etc.
I would thus conclude by stating that coding is not limited to itself, but there are many other aspects that are directly or indirectly dependent on it. So proper care should be taken while documenting the programs. There should be a standard that should be followed.
-- Sujith Nair