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.
* On September 14, 2022
*****************************************/
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.
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.
