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(a < 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