Why PhpDocumentor Drives Me Crazy
Well, actually, phpDocumentor in and of itself doesn’t drive me crazy. It is the people writing sloppy code and doing rather stupid things in the name of creating good documentation. PhpDocumentor has some very noble goals and benefits. Providing proper documentation regarding your code is important, especially open source code which is used by lots o people. But instead of writing proper documentation for well written code, we use documentation to obfuscate the fact we write sloppy code and it seems that phpDocumentor is a part of this, even as an innocent bystander. Maybe phpDocumentor does drive me crazy.
I just finished looking at some code that had a stupid bug in it. My customer apparently had hired someone to write something that never really worked on their web site and they finally got around to trying to get it to work and called me. The text file was ~1500 lines including white space. Of those 1500 lines, 500 lines were actual code, the rest was comments in phpDocumentor format and 52 blank lines. For example, eight accessor methods each consisted of 3 code lines and 9 lines of comments. Worse, the 9 lines of comments provided no additional information regarding the methods other than point out that the 3 lines were poorly written in the first place. The code was not self-documenting, didn’t follow common OOP coding practices, and felt unfinished especially since the accessor methods were never used anywhere. Why were they even written?!?
Here is an actual example:
/**
* Return the value of the variable $Var
*
* Example:
* $myVar = $obj->returnVar()
*
* @access private (technically public since php doesn't do private)
* @return string
* /
function returnVar() {
return $this->Var;
}
Ok, let me first say, I am very anti-php4 OOP. This code was php4 (and apparently ignorant of php5 based on the comment that php doesn’t do private) despite it being written recently (late 2007) and the rest of the site was certainly php5 since I wrote it.
I don’t care what people say, php4 is barely OOP if at all – it is more of a keep people off our back concession until we can do real OOP. People, stop writing php4 OOP code, its stupid! As such, all the data members and methods were public despite the documentation that indicated that certain properties and methods should be private (incidently, s/he was using @access incorrectly here as do many others, using it to indicate what access the property or method should have instead of the level of phpDocumentor access to the documentation). As such, the accessor methods were superfluous. Although all 8 were get type methods, none started with “get” which is common practice (for example, see Object-Oriented PHP by Peter Lavin
With that rant over, what’s so wrong with the actual documentation. Nothing. It is attempting to do what it is suppose to do. If this was a complex piece of code, I could really appreciate the complete documentation. A single instance of this isn’t so bad, but when the entire class file is filled with comments that out weigh the actual code by 3 times, it gets frustrating, especially when the documentation says absolutely nothing that can’t be seen by looking at the actual code!
In the code instance I had to deal with, the bug turned out to be a variable name mistake – yes, $this->Var was mistyped as $this->var. I spent what felt like hours to finally figure it out. My eyes are used to seeing variables starting with lower case. As such, $this->var appeared at glance to be correct.
The documentation for the variable $Var was 5 lines long for the 1 line of actual code and it didn’t actually specify what the variable was used for – its description was “Initial value.” Of WHAT??? Completely silly. What happened to self-documenting code anyway? But to write code that isn’t self-documenting and then to document it with redundant information that doesn’t tell us what it really is for is unforgivable.
I guess this takes me back to the title of this article. PhpDocumentor promotes people to do the right thing, document their code. Unfortunately, it seems that a lot of programmers document their code because they have to or think it is the right thing to do. They follow the basic format for documenting for phpDocumentor without really thinking about the usefulness of their documentation and for whom the documentation was written. In many cases, they write it because they are required to do so to get their code accepted for inclusion in a project.
Because they spend so much time having to document their code, they end up writing really sloppy code! Or, they write sloppy code and then try to fix the confusion it by documenting it instead of re-writing the code to be self-documenting. Often, if you can’t write self-documenting code, you are not going to be able to write good documentation either since you apparently really don’t know what your code is doing!
Because of the documentation comments ratio being 5:1 with property declarations, I had pretty much glossed over all of them. It wasn’t easy to actually find the declaration of the variable. I only realized that the variable was suppose to have an upper case “V” when I started looking at the returnVar() method of which I could find no actual use. That got me to look all over the place including the variable declaration where my initial reaction was, “Hey, s/he screwed up and capitalized the v.” I changed it to lower case and the code suddenly worked and that is when I realized that returnVar() had also used an upper case “V.”
No, the bug wasn’t caused by phpDocumentor or the documentation comments. I didn’t view the documentation as formated by phpDocumentor at all and I am not sure it would have helped to do so. However, the excessive amount of comments compared to the amount of code caused my eyes to gloss over and I missed the obvious for all too long.
Even well accepted public code such as what can be found in the PEAR repositories often seem to miss the point of phpDocumentor. I used a particular PEAR package for a while despite it still being stuck in php4 OOP land but in the end I stopped using it because of this. Even though it has a ton of phpDocumentor comments ( about 35% of the total files ), I found that package, which shall remain unnamed, poorly documented at least for the end user. It had all the required phpDocumentor type comments in order to be accepted into the PEAR repository, producing the proper web page of phpDocumentor generated documentation but quite frankly, WHY? It told me nothing that I couldn’t see by just looking at the code. Oh yeah, it was required to be included in the PEAR repository. *sigh*
A bunch of the PEAR packages suffer from this. Fortunately, the code itself in that package was pretty good about being self-documenting so I got to the point where I stripped out all the comments so I could read the code and figured out how to use it.
This should not happen! If one does phpDocumentor correctly, my guess is anyone could look at the formatted results of passing the code through phpDocumentor and get great documentation. I have to admit, I gave up on trying to write my own because the comments seem to either be redundant to properly written code or overly verbose. I don’t pass my code through phpDocumentor to view the documentation on a web page so I guess in part, that is a problem. I am guessing that a lot of coders do the same, write the phpDocumentor comments and never look at their parsed results.
If we would look at the results of what is being produced, the documentation, we would probably write the comments a lot differently. More importantly, if we had someone who has no contact with our code read the generated documentation and have them tell us what they understand, we might be shocked at how poorly they work. We follow the correct format for phpDocumentor comments ( in reality, there is a lot of inconsistency in this ) and have tons of them in our code but we still don’t say anything useful.
I am not saying we should stop creating well commented code. Rather, we need to really consider why we are commenting it, who our audience is, and what is going to be useful. Finally, I really would like to see a way to have well documented code and yet have the code clean so when I am working with the code itself, I am not having to skip over tons of comments to work on the code. Yes, folding code works but IDE’s need to be better at folding comment blocks too, imho. I have almost gotten to the point where I want to have two copies of my code, one well commented and one that has none. I believe phpDocumentor has a way to do this but I haven’t figure it out yet. Documentation is soooo hard!
And that is why phpDocumentor drives me crazy. I want to do the right thing. PhpDocumentor helps me do the right thing with fairly standardized methods. But well written documentation is not an easy task, no matter what tools we use. We have to really understand what we are doing and be able regurgitate it back to people who may not think the way we do. I will try. 🙂