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.