Is PHPDoc verbosity more trouble than it's worth?

Question

I tried using PHPDoc for the first time today and quickly ran into a problem.

For every 1 line of variable declarations, I had at least 5 lines of comments. Example:

/**
 * Holds path the remote server
 * @name ...
 * @global ...
 */
 $myvar = ...

Of course, the payoffs are nice - but this turns a 10-line config file into a 60-line file. Takes me forever to fill out, and I'm not yet convinced it adds that much over a simple one-liner.

It also throws a kink in my workflow. All is fine and good until I need to make sweeping changes. With my well-documented doc-blocks, all of a sudden I no longer have to refactor my code, but I need to re-write all these tedious details. Wait til the end you say? HAH! Then documentation will never happen.

On top of it all - it forces me into C-style /**/ comments in the middle of my code. This drives me crazy during development since it strips the ability to comment out large blocks on demand. Now to comment out a a large block of code, I need to pull something like :range,s/^/#/ ; then undo it later. Annoying!

Long story short - I like PHPDoc, I love well documented code - but 5 lines of comments for every one line of code is far too much!. Are there features I'm missing? Is this a common problem?

Answer 1

Whether or not it's overkill depends largely on the intended use of your application. If you're writing an app that will only be used by a single company or group, you probably don't need exhaustive documentation of every single variable.

For example, right now I'm working on a project with a fairly extensive code base but very few developers (for now, just me). I'm adding PHPDoc blocks for two things: classes and methods. For everything else, I comment frequently, but not in verbose PHPDoc format. Most of this code will only ever be seen by three or four people, and the information they're going to need is black box info: what do I send to this method, what do I expect to get out of it. They want to know how to get data from a Model, not what an private class variable is for.

If I were writing an app that I intended to distribute to other developers or companies, and I expected them to integrate my app with other systems or extend its functionality, I would place more value on more extensive PHPDoc use. That kind of detail could definitely come in handy during long-term maintenance.

Case in point, my current project will at some point require the creation of an API to be accessed from other sites. You can bet that API will have more comments and written documentation than lines of code.