Geek Answers Handbook

PHP - excessive comment?

I recently started working on a small CMS. I usually develop .NET applications in C #, and I'm very used to commenting on my fields and methods. My friend told me that I have comments in PHP scripts because PHP is dynamic and parsed on demand, so it will take longer to parse the comments.

Is this statement applicable to my situation, which comments on each method and field?

An example of one of my classes:

<?php /* * jWeb * Copyright (C) 2010 AJ Ravindiran * * This program is free software: you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation, either version 3 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program. If not, see <http://www.gnu.org/licenses/>. */ /** * Controls database connections. * * @author AJ Ravindiran * @version 1.0.0 Jan-02-2010 */ class database { /** * The database connection ip address. * @var string */ private $host = ""; /** * The database user name. * @var string */ private $username = ""; /** * The database user password. * @var string */ private $password = ""; /** * The database that this instance will write to, and read from. * @var string */ private $database = ""; /** * Holds the mysql connection instance. * @var resource */ private $connection = null; /** * Whether the instance is connected to the specified database. * @var bool */ private $connected = false; /** * Constructs a new database instance. * @param string $host The database server host. * @param string $port The database server port. * @param string $username The database username authentication. * @param string $password The username specified password. */ public function __construct($host = "localhost", $username = "root", $password = "") { $this->host = $host; $this->username = $username; $this->password = $password; } /** * Connects to the given database. * @param string $database */ public function connect($database) { $this->database = $database; // TODO: handle errors. $this->connection = @mysql_connect($this->host, $this->username, $this->password) or die(); @mysql_select_db($this->database, $this->connection) or die(); /* * If the connection was successful, we can now * identify that the connection is sustained. */ if ($this->connect != null) { $this->connected = true; } } /** * Gets the specified connection details from this instance. * @param boolean $show_details * @return string The connection string. */ public function getConnectionString($show_details = false) { if ($show_details) { return "database[host=" . $this->host . ", port=" . $this->port . ", user=" . $this->username . ", pass=" . $this->password . ", database=" . $this->database . "]"; } else { return "database[host=" . $this->host . ", port=" . $this->port . "]"; } } } ?>
+6
comments coding-style php
source share
8 answers

You have comments and comments. Beginners especially like to translate each line of code into a "readable language."

 // Assign "a" to x. $x = "a"; // Do stuff with x and get y. $y = do_stuff($x); // Return y. return $y;

While experts (bit), more experienced programmers often do:

 // Do stuff with "a" and return it. $x = "a"; $y = do_stuff($x); return $y;

or even

 // Do stuff with "a" and return it. return do_stuff("a");

Needless to say, the first example is "excessive commentary." However, those comments can also be posted as a comment function. Just write self-evident code, for example. do not use variables like $x , but give it a noun, such as $speed or so, and give the function a verb name, such as increment_speed() or so. Thus, you can simply leave all comments inside the function that are already explained by the code itself.

Over-commenting, however, does not adversely affect performance. Unless this is the number of lines of comments in one line of code, especially if it is an interpretation language. Compiled languages ​​such as Java do not suffer from this; comments are already deleted after compilation.

Update : You have included sample code; it's really exaggerated to comment on private properties, especially if they already have a self-evident name. Function comments are in order.

+4
source share

Other commentators here are absolutely correct regarding performance. Performance should not be taken into account when commenting in code.

However, to comment on your specific example, I believe that your class has too many comments. For example, take a look at this field:

 /** * The database user name. * @var string */ private $username = "";

There is a lot of “visual noise,” and commentary doesn't explain anything at all. You have 4 lines of comments that do not tell the reader any interesting details. If you want to add a comment, it should explain something interesting about the code, and not just repeat what the code does. For example:

 /** * The database user name. This field has to be 5 to 10 characters long. It * is not required if the connection security is disabled. * @var string */ private $username = "";

To choose another example, take a look at this comment:

 /** * Gets the specified connection details from this instance. * @param boolean $show_details * @return string The connection string. */ public function getConnectionString($show_details = false) { ...

This comment is a good start, but it does not contain important information: what exactly does the show_details parameter show_details ? What details will be missing if they are not included? Or what will be included when it is turned on?

Comments are not fundamentally bad, and more comments are not always worse than fewer comments. It is important to have the right comments!

+25
source share

Your friend says stupidity.

PHP is dynamic and needs to parse scripts on demand, but the time taken to parse the comments is negligible (because as soon as it encounters the comment, it goes to the next line in question, probably only a little more overhead than spaces) and the value of the comments to yourself and future system supporters is much more than any potential performance.

Feel free to comment liberally.

You can significantly speed up PHP by using an operation code caching mechanism such as APC or eCache. Invest your efforts and time in real solutions like these, rather than supposed stupidity like missing comments.

+10
source share

This is b * llshit, the number of comments has nothing to do or is very little related to the actual processing time, since comments are not parsed.

The more informative comments you have in your code, the better it will be for the next one who needs to support it.

The comment style presented in your sample code is exemplary, because you use comments where comments are needed, and you use phpdoc syntax to make creating documentation easy.

Some may critically comment on each class variable, but in my opinion, the point of using phpdoc syntax is that every significant variable, method and class have an explanation.

+7
source share

Comment as much as you need to understand the meaning of your code. The time that you get, if any, in the absence of comments on parsing is suppressed by pain while maintaining opaque code.

However, the comments should be meaningful, and you have a little more than necessary. For example:

 /** * The database that this instance will write to, and read from. * @var string */ private $database = "";

I am wondering if a big comment adds anything here to your code.

+5
source share

Do not listen to your friend. You should not worry about optimizing microproductivity if you have not profiled your application and found that most of the time it parses comments in your PHP files (and most likely it does not exist ... you will need many, many megabytes of comments for it should be noticeable).

There are many other ways that you can start the application slowly, for example, using the wrong data structures or improperly setting up your database. Removing all comments simply confuses other programmers, which is likely to lead to malfunctions (and more importantly: logical errors).

+3
source share

I would think that the case of an absurd counterproductive premature microoptimization:

  • Ignoring comments is just the least complex and time-consuming part of the analysis.
  • If performance is important, you'll want to use a server that caches PHP bytecode anyway, which makes the parsing unnecessary
  • Never trade maintainability for performance unless you have hard data proving that you have performance issues and where it is located.
+3
source share

If performance is a priority for your PHP code, you should use a bytecode cache, for example:

The bytecode caches the storage code that was parsed and compiled into bytecode. Subsequent execution of the same PHP page should not parse the code, not to mention the comments.

Therefore, code comments affect performance only in application deployments that do not care about performance.

0
source share

More articles:


All Articles