Writing Self-Documenting PHP Code

There are two things that developers hate.

Fixing bugs. And writing documentation.

Now, while the first can be handled through better planning and execution, it's the second one that really gets a developer's goat. Most developers can't stand the thought of documenting their own code, finding it both tedious and a waste of their time and skills (although, strangely enough, they're the first to complain about the "lack of documentation" when it comes to someone else's code.)

The fact of the matter, though, is that you're fooling yourself if you think that you can survive without documentation. Properly-documented application code makes it easier to trace and squash bugs, to maintain code over the long run, and to improve both the productivity of the programmer and the quality of the software. You can't avoid it, and so you're just going to have to grow up and learn to live with it.

And that's where this article comes in. Over the next few pages, I'm going to introduce you to PHPDoc, a documentation system for PHP that relies on comments within your code to automatically generate documentation for your PHP classes. As you will see, using PHPDoc can simplify the task of creating API documentation and thereby save you a significant amount of time in the post-release phase of a software project.

>>> More PHP Articles          >>> More By Harish Kamath, (c) Melonfire

blog comments powered by Disqus