Why PhpDocumentor Drives Me Crazy

Well, actu­ally, php­Doc­u­men­tor in and of itself doesn’t drive me crazy. It is the peo­ple writ­ing sloppy 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 proper doc­u­men­ta­tion regard­ing your code is impor­tant, espe­cially open source code which is used by  lots o peo­ple. But instead of writ­ing proper doc­u­men­ta­tion for well writ­ten code,  we use doc­u­men­ta­tion to obfus­cate the fact we write sloppy code and it seems that php­Doc­u­men­tor is a part of this, even as an inno­cent bystander. Maybe php­Doc­u­men­tor does drive me crazy.

I just fin­ished look­ing at some code that had a stu­pid bug in it. My cus­tomer appar­ently had hired some­one to write some­thing that never really worked on their web site and they finally 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 actual code, the rest was com­ments in php­Doc­u­men­tor for­mat and 52 blank lines. For exam­ple,  eight acces­sor meth­ods each con­sisted of 3 code lines and 9 lines of com­ments. Worse, the 9 lines of com­ments pro­vided no addi­tional infor­ma­tion regard­ing the meth­ods other than point out that the 3 lines were poorly writ­ten in the first place. The code was not self-documenting, didn’t fol­low com­mon OOP cod­ing prac­tices, and felt unfin­ished espe­cially since the acces­sor meth­ods were never used any­where. Why were they even written?!?

Here is an actual 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­ently igno­rant of php5 based on the com­ment that php doesn’t do pri­vate) despite it being writ­ten recently (late 2007) and the rest of the site was cer­tainly php5 since I wrote it.

I don’t care what peo­ple say, php4 is barely 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­cated that cer­tain prop­er­ties and meth­ods should be pri­vate (inci­dently, s/he was using @access incor­rectly here as do many oth­ers, using it to indi­cate what access the prop­erty or method should have instead of the level of php­Doc­u­men­tor 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 started 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 started 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 actual 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 really 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 actual code by 3 times, it gets frus­trat­ing, espe­cially when the doc­u­men­ta­tion says absolutely noth­ing that can’t be seen by look­ing at the actual 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 finally fig­ure it out. My eyes are used to see­ing vari­ables start­ing with lower case. As such, $this->var appeared at glance to be correct.

The doc­u­men­ta­tion for the vari­able $Var was 5 lines long for the 1 line of actual code and it didn’t actu­ally spec­ify what the vari­able was used for — its descrip­tion was “Initial value.” Of WHAT??? Completely silly. What hap­pened to self-documenting code any­way? But to write code that isn’t self-documenting and then to doc­u­ment it with redun­dant infor­ma­tion that doesn’t tell us what it really is for is unforgivable.

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 php­Doc­u­men­tor with­out really 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 cases, they write it because they are required to do so to get their code accepted 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 really sloppy code! Or, they write sloppy code and then try to fix the con­fu­sion it by doc­u­ment­ing 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 doc­u­men­ta­tion either since you appar­ently really don’t know what your code is doing!

Because of the doc­u­men­ta­tion com­ments ratio being 5:1 with prop­erty dec­la­ra­tions, I had pretty much glossed over all of them. It wasn’t easy to actu­ally 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 started look­ing at the return­Var()  method of which I could find no actual 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 lower case and the code sud­denly worked and that is when I real­ized that return­Var() had also used an upper case “V.”

No, the bug wasn’t caused by php­Doc­u­men­tor or the doc­u­men­ta­tion com­ments. I didn’t view the doc­u­men­ta­tion as for­mated by php­Doc­u­men­tor 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 accepted pub­lic code such as what can be found in the PEAR repos­i­to­ries often seem to miss the point of php­Doc­u­men­tor. 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 php­Doc­u­men­tor com­ments ( about 35% of the total files ), I found that pack­age, which shall remain unnamed, poorly doc­u­mented at least for the end user. It had all the required php­Doc­u­men­tor type com­ments in order to be accepted into the PEAR repos­i­tory, pro­duc­ing the proper web page of php­Doc­u­men­tor gen­er­ated 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 included in the PEAR repos­i­tory. *sigh*

A bunch of the PEAR pack­ages suf­fer from this. Fortunately, the code itself in that pack­age was pretty good about being self-documenting 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 php­Doc­u­men­tor cor­rectly, my guess is any­one could look at the for­mat­ted results of pass­ing the code through php­Doc­u­men­tor 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­erly writ­ten code or overly ver­bose. I don’t pass my code through php­Doc­u­men­tor 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 php­Doc­u­men­tor com­ments and never 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­ently. More impor­tantly, if we had some­one who has no con­tact with our code read the gen­er­ated doc­u­men­ta­tion and have them tell us what they under­stand, we might be shocked at how poorly they work. We fol­low the cor­rect for­mat for php­Doc­u­men­tor com­ments ( in real­ity, there is a lot of incon­sis­tency in this ) and have tons of them in our code but we still don’t say any­thing useful.

I am not say­ing we should stop cre­at­ing well com­mented code. Rather, we need to really con­sider why we are com­ment­ing it, who our audi­ence is, and what is going to be use­ful. Finally, I really would like to see a way to have well doc­u­mented 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­mented and one that has none. I believe php­Doc­u­men­tor has a way to do this but I haven’t fig­ure it out yet. Documentation is soooo hard!

And that is why php­Doc­u­men­tor dri­ves me crazy. I want to do the right thing. PhpDocumentor helps me do the right thing with fairly 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 really 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.