[wp-hackers] Proposal for a function commenting convention

[Travis Snoozy]

On Sat, 13 Oct 2007 22:48:07 -0700, "Robin Adrianse"
<robin.adr at gmail.com> wrote:

> I highly doubt it, but someone more knowledgeable about the PHP code
> would know for sure.
> 
> On 10/13/07, Matt <speedboxer at gmail.com> wrote:
> >
> > Ya... but... would documenting all (or most) of the functions make
> > a huge impact on load times on the files since they'll be loaded
> > with useless (in the executing sense) comments?

When in doubt, get some numbers. ;) I'm actually sort of surprised at
the results I got.

There does seem to be a distinct overhead involved with parsing
comments. Specifically, I observed a 7.5% increase in the test load's
average run time, and (assuming that the difference between the
commented/non-commented times on the test load can be added to the
non-commented average page generation time) a possible 12.2% increase
in page generation time.

My assumptions/setup are laid out as follows:

* In wordpress 2.3, the string "function " comes up 2,425 times. A
very conservative estimate would put every one of these instances as a
function declaration that's part of the API.

* Assuming each function takes an average of 1000 total comment
characters to document (almost certainly a low number), that's 2,425,000
characters of comments.

* Comments were split into 1000-character blocks (multi-line) -- one
giant multi-line comment took substantially longer to parse, but was
inconsistent with the actual comment pattern that would be used.

* All tests were performed on the same box, using
PHP 5.2.4_p20070914-pl2-gentoo, and WordPress 2.3/MySQL 5.0.44/Apache
2.2.6 (where applicable).


Here's the data I collected (using the "time" command):


Running a file containing only the comments:
real    0m0.153s	real    0m0.148s	real    0m0.143s
user    0m0.083s	user    0m0.083s	user    0m0.080s
sys     0m0.003s	sys     0m0.003s	sys     0m0.007s

Average real: 0.148s


Echoing zero to a million to /dev/null (with comments):
real    0m1.575s	real    0m1.586s	real    0m1.578s
user    0m1.373s	user    0m1.337s	user    0m1.340s
sys     0m0.137s	sys     0m0.180s	sys     0m0.183s

Average real: 1.580s


Echoing zero to a million to /dev/null with no comments:
real    0m1.467s	real    0m1.464s	real    0m1.465s
user    0m1.253s	user    0m1.327s	user    0m1.323s
sys     0m0.203s	sys     0m0.127s	sys     0m0.133s

Average real: 1.465s


Running an empty file (<?php?>):
real    0m0.021s	real    0m0.023s	real    0m0.023s
user    0m0.020s	user    0m0.020s	user    0m0.020s
sys     0m0.000s	sys     0m0.003s	sys     0m0.003s


Dumping the commented code file to /dev/null with cat:
real    0m0.003s	real    0m0.006s	real    0m0.004s
user    0m0.000s	user    0m0.000s	user    0m0.000s
sys     0m0.003s	sys     0m0.007s	sys     0m0.003s


For reference, these are the times it took to load the front page of my
test blog (on the same machine as these other tests were performed):
1.076 seconds
0.810 seconds
0.948 seconds

Average generation time: 0.945s


And just for the curious...
Running a file with one huge comment (~2.4 million chars):

real    0m0.726s	real    0m0.731s	real    0m0.714s
user    0m0.633s	user    0m0.653s	user    0m0.630s
sys     0m0.017s	sys     0m0.000s	sys     0m0.023s



7-12% is a pretty big performance hit -- even a 4-5% improvement in
script running time would still be worth considering optimization in
many circumstances. Thus, it may be beneficial, if substantial
commenting is added, to strip that commenting out in the distributed
zipfile that's intended for deployment. Of course, we'll only know the
actual impact once all those comments are there, but the ballpark
figures would seem to indicate that it's worth keeping an eye on.


-- 
Travis 

In Series maintainer
Random coder & quality guy
<http://remstate.com/>