I am currently working on a project where I decided to use phpDocumentor, also known as PHPDoc. I admit this was an arbitrary decision. I have not used the software before and saw this project as a chance to try it out. Today I felt like sharing my initial thoughts on it.
Not a Substitute for Documentation
Let me begin by stating one of my strong opinions about programming: documentation generated from source code alone is not good enough. If the only documentation for a project is Javadoc-style HTML mapping out class hierarchies and parameter and return values then that project is not fully, properly documented. I firmly believe that all software should have ‘hand-written’ documentation explaining the program is clear, concise writing.
If program has nothing but generated API documentation then it is not well-documented in my opinion.
It is not like I believe tools like PHPDoc are useless. Far from it. I am finding PHPDoc to be a useful addition to my toolbox.
The project I’m working on is a server-side application that other programmers and web designers will communicate with from the front-end of a website. Having comprehensive API documentation generated from the source code makes that communication easier and smoother to achieve. If another programmer needs to see specific details about the methods of a class, well there they are, thanks to PHPDoc.
I am also discovering that writing out blocks of detailed PHPDoc material before writing code is helping me visualize that code and notice design issues early. In this regard it helps the same way that test-driven development does—something else I am making use of in this project via PHPUnit, which I will write about another day.
I am hoping that PHPDoc will result in cleaner, easier to understand code, particularly for the other developers who will be making use of my code. If so then it has done its job. So far it is succeeding at this goal, but the project is far from over.
When I’m done with the program I will follow this up with another article with my feelings about the specifics of PHPDoc, its syntax, how it affects the readability of code, and so forth.