Initial Thoughts on Using phpDocumentor

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.

That Said…

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.

Expectations

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.

Advertisements

3 thoughts on “Initial Thoughts on Using phpDocumentor

  1. […] Previously I wrote about my intent to use phpDocumentor on a project. I have since switched to using ApiGen. Gradually I became less happy with the formatting of phpDocumentor’s output. You can customize that but honestly it was easier to switch to another tool than to setup a theme that I wanted. ApiGen already understands all of the annotations I was using, so I had to change nothing within my code. And in my opinion its output is easier to read and easier to browse. […]

Add Your Thoughts

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s