Comprehensible PHP Code

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.