Why PhpDocumentor Drives Me Crazy

Well, actu­al­ly, phpDocumentor in and of itself doesn’t dri­ve me crazy. It is the peo­ple writ­ing slop­py code and doing rather stu­pid things in the name of cre­at­ing good doc­u­men­ta­tion. PhpDocumentor has some very noble goals and ben­e­fits. Providing prop­er doc­u­men­ta­tion regard­ing your code is impor­tant, espe­cial­ly open source code which is used by  lots o peo­ple. But instead of writ­ing prop­er doc­u­men­ta­tion for well writ­ten code,  we use doc­u­men­ta­tion to obfus­cate the fact we write slop­py code and it seems that phpDocumentor is a part of this, even as an inno­cent bystander. Maybe phpDocumentor does dri­ve me crazy.

I just fin­ished look­ing at some code that had a stu­pid bug in it. My cus­tomer appar­ent­ly had hired some­one to write some­thing that nev­er real­ly worked on their web site and they final­ly got around to try­ing to get it to work and called me. The text file was ~1500 lines includ­ing white space. Of those 1500 lines, 500 lines were actu­al code, the rest was com­ments in phpDocumentor for­mat and 52 blank lines. For exam­ple,  eight acces­sor meth­ods each con­sist­ed of 3 code lines and 9 lines of com­ments. Worse, the 9 lines of com­ments pro­vid­ed no addi­tion­al infor­ma­tion regard­ing the meth­ods oth­er than point out that the 3 lines were poor­ly writ­ten in the first place. The code was not self-doc­u­ment­ing, didn’t fol­low com­mon OOP cod­ing prac­tices, and felt unfin­ished espe­cial­ly since the acces­sor meth­ods were nev­er used any­where. Why were they even writ­ten?!?

Here is an actu­al exam­ple:

* 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 appar­ent­ly igno­rant of php5 based on the com­ment that php doesn’t do pri­vate) despite it being writ­ten recent­ly (late 2007) and the rest of the site was cer­tain­ly php5 since I wrote it.

I don’t care what peo­ple say, php4 is bare­ly OOP if at all — it is more of a keep peo­ple off our back con­ces­sion until we can do real OOP. People, stop writ­ing php4 OOP code, its stu­pid! As such, all the data mem­bers and meth­ods were pub­lic despite the doc­u­men­ta­tion that indi­cat­ed that cer­tain prop­er­ties and meth­ods should be pri­vate (inci­dent­ly, s/he was using @access incor­rect­ly here as do many oth­ers, using it to indi­cate what access the prop­er­ty or method should have instead of the lev­el of phpDocumentor access to the doc­u­men­ta­tion). As such, the acces­sor meth­ods were super­flu­ous. Although all 8 were get type meth­ods, none start­ed with “get” which is com­mon prac­tice (for exam­ple, see Object-Oriented PHP by Peter Lavin). Moreover, the method names were not con­sis­tent, some start­ed with “return” oth­ers “show.” Finally, there were no set acces­sor meth­ods to bal­ance the gets. Of course, since all the data mem­bers were pub­lic, there was no need to have a set method any more was there a need for a get method.

With that rant over, what’s so wrong with the actu­al doc­u­men­ta­tion. Nothing. It is attempt­ing to do what it is sup­pose to do. If this was a com­plex piece of code, I could real­ly appre­ci­ate the com­plete doc­u­men­ta­tion. A sin­gle instance of this isn’t so bad, but when the entire class file is filled with com­ments that out weigh the actu­al code by 3 times, it gets frus­trat­ing, espe­cial­ly when the doc­u­men­ta­tion says absolute­ly noth­ing that can’t be seen by look­ing at the actu­al code!

In the code instance I had to deal with, the bug turned out to be a vari­able name mis­take — yes, $this->Var was mistyped as $this->var.  I spent what felt like hours to final­ly fig­ure it out. My eyes are used to see­ing vari­ables start­ing with low­er case. As such, $this->var appeared at glance to be cor­rect.

The doc­u­men­ta­tion for the vari­able $Var was 5 lines long for the 1 line of actu­al code and it didn’t actu­al­ly spec­i­fy what the vari­able was used for — its descrip­tion was “Initial val­ue.” Of WHAT??? Completely sil­ly. What hap­pened to self-doc­u­ment­ing code any­way? But to write code that isn’t self-doc­u­ment­ing and then to doc­u­ment it with redun­dant infor­ma­tion that doesn’t tell us what it real­ly is for is unfor­giv­able.

I guess this takes me back to the title of this arti­cle. PhpDocumentor pro­motes peo­ple to do the right thing, doc­u­ment their code. Unfortunately, it seems that a lot of pro­gram­mers doc­u­ment their code because they have to or think it is the right thing to do. They fol­low the basic for­mat for doc­u­ment­ing for phpDocumentor with­out real­ly think­ing about the use­ful­ness of their doc­u­men­ta­tion and for whom the doc­u­men­ta­tion was writ­ten. In many cas­es, they write it because they are required to do so to get their code accept­ed for inclu­sion in a project.

Because they spend so much time hav­ing to doc­u­ment their code, they end up writ­ing real­ly slop­py code! Or, they write slop­py code and then try to fix the con­fu­sion it by doc­u­ment­ing it instead of re-writ­ing the code to be self-doc­u­ment­ing. Often, if you can’t write self-doc­u­ment­ing code, you are not going to be able to write good doc­u­men­ta­tion either since you appar­ent­ly real­ly don’t know what your code is doing!

Because of the doc­u­men­ta­tion com­ments ratio being 5:1 with prop­er­ty dec­la­ra­tions, I had pret­ty much glossed over all of them. It wasn’t easy to actu­al­ly find the dec­la­ra­tion of the vari­able. I only real­ized that the vari­able was sup­pose to have an upper case “V” when I start­ed look­ing at the returnVar()  method of which I could find no actu­al use. That got me to look all over the place includ­ing the vari­able dec­la­ra­tion where my ini­tial reac­tion was, “Hey, s/he screwed up and cap­i­tal­ized the v.” I changed it to low­er case and the code sud­den­ly worked and that is when I real­ized that returnVar() had also used an upper case “V.”

No, the bug wasn’t caused by phpDocumentor or the doc­u­men­ta­tion com­ments. I didn’t view the doc­u­men­ta­tion as for­mat­ed by phpDocumentor at all and I am not sure it would have helped to do so. However, the exces­sive amount of com­ments com­pared to the amount of code caused my eyes to gloss over and I missed the obvi­ous for all too long.

Even well accept­ed pub­lic code such as what can be found in the PEAR repos­i­to­ries often seem to miss the point of phpDocumentor. I used a par­tic­u­lar PEAR pack­age 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 com­ments ( about 35% of the total files ), I found that pack­age, which shall remain unnamed, poor­ly doc­u­ment­ed at least for the end user. It had all the required phpDocumentor type com­ments in order to be accept­ed into the PEAR repos­i­to­ry, pro­duc­ing the prop­er web page of phpDocumentor gen­er­at­ed doc­u­men­ta­tion but quite frankly, WHY? It told me noth­ing that I couldn’t see by just look­ing at the code. Oh yeah, it was required to be includ­ed in the PEAR repos­i­to­ry. *sigh*

A bunch of the PEAR pack­ages suf­fer from this. Fortunately, the code itself in that pack­age was pret­ty good about being self-doc­u­ment­ing so I got to the point where I stripped out all the com­ments so I could read the code and fig­ured out how to use it.

This should not hap­pen! If one does phpDocumentor cor­rect­ly, my guess is any­one could look at the for­mat­ted results of pass­ing the code through phpDocumentor and get great doc­u­men­ta­tion. I have to admit, I gave up on try­ing to write my own because the com­ments seem to either be redun­dant to prop­er­ly writ­ten code or over­ly ver­bose. I don’t pass my code through phpDocumentor to view the doc­u­men­ta­tion on a web page so I guess in part, that is a prob­lem. I am guess­ing that a lot of coders do the same, write the phpDocumentor com­ments and nev­er look at their parsed results.

If we would look at the results of what is being pro­duced, the doc­u­men­ta­tion, we would prob­a­bly write the com­ments a lot dif­fer­ent­ly. More impor­tant­ly, if we had some­one who has no con­tact with our code read the gen­er­at­ed doc­u­men­ta­tion and have them tell us what they under­stand, we might be shocked at how poor­ly they work. We fol­low the cor­rect for­mat for phpDocumentor com­ments ( in real­i­ty, there is a lot of incon­sis­ten­cy in this ) and have tons of them in our code but we still don’t say any­thing use­ful.

I am not say­ing we should stop cre­at­ing well com­ment­ed code. Rather, we need to real­ly con­sid­er why we are com­ment­ing it, who our audi­ence is, and what is going to be use­ful. Finally, I real­ly would like to see a way to have well doc­u­ment­ed code and yet have the code clean so when I am work­ing with the code itself, I am not hav­ing to skip over tons of com­ments to work on the code. Yes, fold­ing code works but IDE’s need to be bet­ter at fold­ing com­ment blocks too, imho.  I have almost got­ten to the point where I want to have two copies of my code, one well com­ment­ed and one that has none. I believe phpDocumentor has a way to do this but I haven’t fig­ure it out yet. Documentation is soooo hard!

And that is why phpDocumentor dri­ves me crazy. I want to do the right thing. PhpDocumentor helps me do the right thing with fair­ly stan­dard­ized meth­ods. But well writ­ten doc­u­men­ta­tion is not an easy task, no mat­ter what tools we use. We have to real­ly under­stand what we are doing and be able regur­gi­tate it back to peo­ple who may not think the way we do. I will try. 🙂

Leave a Reply