The bad choices of PHPDoc.
Space-asterisk comments are bad.
/**
*
*/I imagine the use of space-asterisk, back in C, was necessary when syntax highlighting was not a thing, and you needed your documentation comments to stand out from the rest of the un-highlighted code.
Today, it serves little purpose. A document block comment is started with a “/**”. There should be no need for a continuation of a “*” on every line. Not only should there be no need, but it interferes with the normal use of the comment space. Let’s say I wanted to place some markdown in my block comment documentation. Let’s s assume the best case scenario where I have an editor that automatically adds the ‘ *’ for my pasted markdown text. Even in this best case scenario, the ” *” interferes with the use of documentation. For a programmer reading the markdown, they would extract the markdown and put it into a markdown syntax highlighter. But this now means the programmer has to remove all the ” *” before the markdown lines.
This same issue occurs with other things, such as examples. Say I have an example in the doc that can be copied and run. Well, now the programmer has to remove the ” *” before doing this.
Space asterisk is a cluttering remnant.
Design For Humans, Adapt With Machines
The PHPDoc standard itself is unnecessarily verbose.
@param string $name description
function($name){}Here, the fact the first line is describing the $name parameter is buried.
Let’s look at the situation for multiple params
/**
* @param int $name description
* @param string $age description
* @param string $gender description
*/
function user_create($name, $age, $gender){}Let’s compare this to something I made
/** params
< name > < t: string> < description >
< age > < t: int> < description >
< gender > < t: string> < description >
*/
function user_create($name, $age, $gender){}If you are used to DocBlock comments, the effort to read both is probably the same. If you are not, mine is easier to read. Both of these can be parsed by a program – that is not a limitation.
My point here is not to say my way is the best, but to say, the structure of the documenting comment should be designed on the principles of:
- how easily/quickly can the doc be written, so as not to detract from the main productivity of writing code
- how well can the comment describe the thing while conforming to the standard
- how easily can the comment be viewed and interpreted by humans
As for PHPDocumentor, defining the parameter structure is very limited. This is especially bad for PHP where functions are often handling anonymous structures, which complex hierarchy.
You can make a documenting comment describe the complexity of a parameter. I explain how I do so in Standard Coding.
This requires a bit more from the comment parsing program. But, that should not be the limitation. Should thousands of programmers be limited in their commenting form b/c commenting parsers couldn’t spend an hour adding more complex comment parsing?
Does it matter?
The momentum of Docblocks in PHP is high, and this probably won’t change for a time. But as typing becomes more common in PHP, Docblock won’t matter that much for IDEs. Personally, I have almost never found a use in IDE automated code handling based on Docblocks, accept, perhaps, way back when I started Java, and then again when I started C#. For large projects, I always found that it is important to have a tool that allows me to easily navigate the source tree, and this can be done with something like doxygen. And, for that reason, I’m apt not to care about IDE compatibility for block comments, but I am apt to care about doxygen compatibility – and Doxygen supports block comments without the space-asterisk.
Let’s compare Doxygen param description with a PHPDoc param. PHPDoc:
/** PHPDoc
* @param int $age the age of the person
*/
/** Doxygen
@param age the age of the person
*/Consider that, with type declarations within PHP, specifying the type becomes redundant, making the ‘int’ placement before the variable name even more unnecessarily obtrusive. But, beyond this minor issue, Doxygen has support for defining multiple variables on one line, for referencing other parameters, and for describing whether a parameter will have its referential value changed.
But, coming back to reality again, most user functions in PHP don’t change referential values, and any commenting that provides the following information is probably sufficient:
- parameter value and type described
- return value and type described
- function and class descriptions
- documentation on use cases, preferable with every non-apparent public function
The first three can be done with either PHPDoc or Doxygen, but the last item, the capacity to provide examples, is deficient in both.