Opinions on PHPDOC as a documentation aid
Posted on 2010-08-16
PHPDOC has been around as a documentation standard for a while and is obviously based on JavaDoc. The ability to generate pages of HTML documentation is obviously nice but it does have the downside of producing documentation that is not directly tied in to the source code - over time the source code can change but the documentation does not (unless you remember to regenerate it).
The other aspects are
1) The visual appearance of the comments
2) The need to be accurate in producing the comments in a given format
I have always found the format of the comments too visually impactive - the comment takes over and you loose sight of the code very quickly, for instance
protected $email; // Contact email address
protected $name; // Customer's name
as opposed to
* Contact email address
* @var string
* Customer name
* @var string
Even with just two of these, the declaration between the comments is much more visually invisible and when you have a dozen such declarations and comments you soon lose sight of the working code in the sea of comment code
Something deep in my programmer's soul tells me that I should be producing code that can be automatically documented whilst the pragmstist in me shouts that no one ever reads documentation - they read the code instead.
None of the code at present is available for public release so this would be an internal exercise and decision. I can easily enough transform our existing code libraries over to the PHPDOC format by use of a small program and regexes, but should I bother? I'm not convinced so I'd appreciate opinions.