I first used PHPDoc and quickly ran into a problem.
For each 1 line of variable declarations, I had at least 5 lines of comments. Example:
$myvar = ...
Of course, the winnings are good - but that turns a 10-line configuration file into a 60-line file. Takes me forever to fill, and I'm not yet convinced that it adds a lot to a simple one-line.
It also causes cilantro in my workflow. All is well and good, until I need to make radical changes. With my well-documented docking blocks, all of a sudden, I no longer need to reorganize my code, but I need to rewrite all these tedious details. Wait until the end you are talking about? HA! Then there will never be documentation.
On top of that, it forces me to C-style / ** / comments in the middle of my code. This drives me crazy during development, as it blocks the ability to comment on large blocks on demand. Now, to comment on a large block of code, I need to pull out something like: range, s / ^ / # /; then cancel it later. Annoyingly!
In short - I like PHPDoc, I love well-documented code, but 5 lines of comments for each line of code are too many !. Are there features that I'm missing? Is this a common problem?
source
share