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

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.