Documenting PHP Code - does it hurt performance?

Question

I can't believe anyone would normally object to documentation and comments, but whats the best practice (and practical) for doing so in PHP?

In JavaScript, you can document your code and then run a minimizer to produce a production version of your code for use. What about in PHP, does the extra lines of text affect performance? Should you keep your documents in another file (which I imagine might be important for API's and frameworks but would slow down your development)?

Edit:

My logic was that it would necessarily take longer because the file size is longer and add more work (though possible negligible) for the parser to sort out. Say you had 1000 lines of code and 500 lines of comments, should you put a summarized version instead and then direct to actual documentation page?

Answer 1

Minimizing javascript is a good idea because the whole code is sent to the client - for code with a lot of comments or clients with slow connections, this could lead to a substantial delay in processing (where substantial could mean seconds..).

This is not the case with PHP - the code executes directly on the server and thus only the processed result is sent to the client. There may be some small overhead whilst the PHP preprocessor parses the code, but I would expect this to be negligable - a few milliseconds at most.

Answer 2

It will increase your file size. But the parser ignores it, so it won't impact performance in terms of execution time, etc.

I think the general consensus is to comment within the actual code. While I suppose you could maintain separate files of documentations with references to your code, I can only imagine how cumbersome that would be to maintain.

Answer 3

Definitely, without question, document your PHP code .. it's already bad enough for someone trying to understand what you've done. Any detriment, and I cannot think of any, to documenting code is completely outweighed by the benefits

I am willing to bet that removing comments from almost any code results in zero noticeable speed improvement.

So the answer to your "best practice is": don't remove comments

Answer 4

The primary difference is that JavaScript has to be sent to the client, so those extra bytes take up resources during transfer. And it's not really important to send the documentation to the client. In PHP on the server side, those comments will be ignored by the parser. So document to your heart's content :)

Answer 5

Adding documentation to your code will in no way impact your performance (neither negatively nor positively). Documenting your code is really important so other people (and yourself after a few months) can figure out what's going on. It may take perhaps one millisecond second longer for the lexer, but that's barely even worth mentioning.

Answer 6

With PHP (like ASP.NET) the code can be compiled on the server and HTML generated to be sent down the wire to the client.

PHP source code is compiled on-the-fly to an internal format that can be executed by the PHP engine. In order to speed up execution time and not have to compile the PHP source code every time the webpage is accessed, PHP scripts can also be deployed in executable format using a PHP compiler.

Source

During this process the comments are ignored and play no further part in proceedings. They don't slow down the compiler and hence don't affect performance.

You should comment your code (where appropriate) and keep the comments with the source code. Otherwise there's an even greater chance that they'll get out of step with the code and then worse than useless.

Answer 7

No. Does not affect performance, but it will affect your readability. A wise man once said "Comment as if the next guy to maintain your code is a homicidal maniac who knows where you live.”

Answer 8

the parser will ignore it. keep the documentation there and never skimp on it. the more comments the better.

Answer 9

If you assume an O(1) CPU cost for every comment character, and your code is 4k, and half of the code is comments, then you waste 2k basic operations. With modern processors, a basic operation is ~ 20 clock cycles, but since there's pipeline optimizations, we can assume maybe 5 cycles per operation. Since we're dealing with gigahertz CPUs these days, 2k/1g * 5 ~= 1/10,000th of a second wasted on comment parsing.

Comment your code!

Negligible elements:

• 4k is one partition block, so disk reads are minimized. You'll have to go to disk anyway for the program code. CPUs have enough cache, so the whole program will be held in memory, comments and all.
• Context switching events are likely to occur, but the amount of time executing PHP code is much greater than the amount of time ignoring comments.
• The interpreter must maintain state, so any state-maintenance is not included in the processing time. Why? Because once we know we're in a comment, we just continue reading until we detect end of comment. All O(1) per character except when starting/ending a comment.
• Setup/teardown execution of PHP is neglected because comment-detection would occur regardless of comments existing or not. The lack of comments in your code does not prevent the interpreter from attempting to detect comments. Therefore, no speedups to you.

Comment your code!

Answer 10

When using docblocks for commenting your classes/functions/variables etc, it allows IDE's that support code suggestion/highlighting to give you information about the resuources that you are using as you write. Also, when it comes to creating documentation, there are various tools out there to automate this process using docblocks; in short, if you comment correctly then you already have created your documentation too.

In terms of efficiency, yes the parser will have to filter out comments when the file is loaded into memory (along with white-space I might add). However, this filtering process is run only once at the server and before the php script itself runs which itself will take considerably longer to run. This means that the proportion of time spent on the execution of the intended PHP will be much less comparatively and therefore any decrease in efficiency will be negligible.

Also, think of the time that you will save your successors; that is reason enough ;)