[wp-hackers] Inline Documentation Effort was a Failure

[Jacob Santos]

Matt wrote:
> On Tue, May 27, 2008 at 9:22 PM, Jacob Santos <wordpress at santosj.name> wrote:
>   
>> You are both wrong and right at the same time Matt. The short and sweet of
>> it is that you'll gain more optimizing or removing functions then you would
>> ever see removing functions from code. Read below for why.
>>     
>
> Where was I wrong then? I never said there would be any significant
> performance improvements, just that without comments, it's faster
> (even if by nano-seconds) then with comments. Which is a *little* less
> load on the server, which is always good.
>
>   
That line should read, "...gain more optimizing or removing functions 
then you would ever see removing comments..." sorry for the ambiguous 
statement. A little less load would only be good if you had as much 
traffic as Yahoo, Facebook, or another very high traffic site where 
every ounce of performance gain would be worth it.

When doing optimizations you want to get the most "bang for your buck"? 
Gaining a possible millisecond or two or whatever which is unmeasurable 
compared to the time it would take to write the build script is not 
worth it. This is compared to the time you would gain from optimizing 
other parts of WordPress, which would gain more of an notable 
performance increase.

Furthermore, as it has been mentioned, if you use Opcode Caching, it 
mutes the point completely because once the comments are removed, the 
opcodes are passed to the opcode caching and stored. Comments are not 
part of any opcode cache, therefore, if you really wanted to remove 
comments and gain true performance from doing so, you would need to use 
the opcode cache.

There isn't any more load removing comments then there is removing 
whitespace, then there is parsing foreach, function names, variable 
names, etc. It is all part of the same parsing cycle and unless you want 
to get into the Zend Engine core in order to find out what it is. I 
would be very interested to know.

What it is, is a theory that because most characters have to be looked 
at that comments would slow down parsing. With as quickly as it can 
parse the entire WordPress code base I'll say a few comments here or 
there in every file won't cause a difference. That is my theory.

What I think you are wrong then, is that you aren't weighing the 
importance of documentation compared to the small gain of its removal?

You know, I'm going to do some more research on the matter. There might 
actually be a way to tell how long it took between the start of request 
(however, I'll have to ask the PHP Internals list what that means), the 
time XDebug says the script took, and the difference between the start 
of the request and the end of the request. If this experiment is 
correct, then it, in theory, might be able to tell us how long PHP took 
for the first stage as compared to the second stage.

Then basically, I'll need to write a script that (ironically) needs to 
remove all of the comments and run through the process again. It would 
be better if others who had XDebug could help, because I don't trust my 
personal machine which runs a lot of processes in the background to 
accurately tells. The start of the request, might also be the start of 
the second stage and not the first stage as I hope.

The problem is that in order to prove my point, I must speak in 
absolutes in order to counter your argument. There aren't any. I will 
say that must users of WordPress will not see a difference with or 
without comments, so what other advantage do comments have that would 
justify its existence in the WordPress core?

I would edit this long email down, but I have to go to work and I don't 
have time for editing out the parts I don't need.

-- 

Jacob Santos

http://www.santosj.name - blog
http://funcdoc.wordpress.com - WordPress Documentation Blog/Guide Licensed under GPLv2

Also known as darkdragon and santosj on WP trac.