PHP - Сверхкомментарий?
Я недавно начал работать над маленьким CMS. Я обычно разрабатываю приложения.NET в C#, и я очень привык к комментарию моих полей и методов. Мой друг сказал мне earler, что наличие комментариев в Сценариях PHP довольно плохо, так как PHP является динамичным и проанализирован при необходимости, таким образом имение необходимость проанализировать комментарии займет больше времени.
Этот оператор относится к моей ситуации, которая комментирует каждый метод и поле?
Пример одного из моих классов:
<?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's name.
* @var string
*/
private $username = "";
/**
* The database user's 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's username authentication.
* @param string $password The username's 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 . "]";
}
}
}
?>
8 ответов
Вы комментируете и комментируете. Особенно начинающие нравится переводить каждую линейку кода в «человеческий читаемый язык».
// Assign "a" to x.
$x = "a";
// Do stuff with x and get y.
$y = do_stuff($x);
// Return y.
return $y;
В то время как Эксперты (BIT) более опытные программисты часто просто делают:
// Do stuff with "a" and return it.
$x = "a";
$y = do_stuff($x);
return $y;
или даже
// Do stuff with "a" and return it.
return do_stuff("a");
, не то, чтобы сказать, что первый - пример «чрезмерного комментирования». Однако такие комментарии могут также быть идеально размещены в качестве функционального комментария. Просто напишите самостоятельный код, например, Не используйте переменные, такие как $ x , но дайте ему имя имя , как $ Speed или так и дайте функции глагол имя , как risuretion_speed () или около того. Таким образом, вы можете просто оставить все комментарии внутри функции, которые уже объяснены самим кодом.
«Перевысение», однако не вредно . Если это не зацикливание строк комментариев на одной строке кода, особенно если это интерпретация языка. Компилированные языки, такие как Java, не страдают от этого; Комментарии уже удалены после компиляции.
Обновление : вы включали код код; Действительно, переубивается, чтобы комментировать частные свойства, особенно если у них уже есть самосознание. Комментарии к функциям в порядке.
Ваш друг говорит глупости.
PHP динамичен и должен разбирать скрипты по запросу, но время, необходимое для разбора комментариев, ничтожно мало (потому что как только он сталкивается с комментарием, он опускается на следующую соответствующую строку; вероятно, это лишь немного больше накладных расходов, чем пробела), а значение комментариев для себя и будущих сопровождающих системы намного, намного больше, чем любое потенциальное падение производительности.
Не стесняйтесь свободно комментировать.
Вы можете значительно ускорить PHP, используя механизм кэширования опкодов, такой как APC или eCache. Инвестируйте свои усилия и время в реальные решения, а не в предполагаемую глупость, как пропустить комментарии.
.Не слушай своего друга. Вам не стоит беспокоиться о микро-оптимизации производительности, если вы не профилировали ваше приложение и не обнаружили, что оно тратит большую часть времени на разбор комментариев в ваших PHP-файлах (и, скорее всего, его там нет...., чтобы его можно было заметить, вам понадобится много, много мегабайт комментариев).
Есть много других способов заставить ваше приложение работать медленно, таких как использование неправильных структур данных или неправильная настройка базы данных. Удаление всех комментариев просто сбивает с толку других программистов, увеличивает вероятность возникновения ошибок производительности (а главное: логических ошибок)
.Если производительность является приоритетом для вашего кода PHP, вы должны использовать кэш байткодов, такой как:
Bytecode cache хранит код, который был разобран и скомпилирован в байткод. Последующее выполнение одной и той же PHP-страницы не требует разбора кода, не говоря уже о комментариях.
Следовательно, комментарии к коду влияют на производительность только при развертывании приложений, которые не заботятся о производительности.
.Это b*llshit, количество комментариев не имеет никакого или очень небольшого отношения к реальному времени обработки, так как комментарии не анализируются.
Чем больше смысловых комментариев у вас в коде, тем лучше будет для следующего, кто будет его поддерживать.
Стиль комментариев, представленный в вашем примере кода, является образцовым, так как вы используете комментарии, где комментарии нужны, и синтаксис phpdoc, что сделает создание документации ветерком.
Некоторые могут критиковать комментирование каждой переменной класса, но, на мой взгляд, в этом смысл использования синтаксиса phpdoc, что каждая значимая переменная, метод и класс имеет объяснение.
.Другие комментаторы здесь совершенно правы в отношении производительности. Производительность не должна быть рассмотрением при комментировании кода.
Однако, чтобы прокомментировать ваш конкретный пример, я считаю, что ваш класс имеет слишком много комментариев в этом. Например, взгляните на это поле:
/**
* The database user's name.
* @var string
*/
private $username = "";
Там есть много «визуального шума», и комментарий ничего не объясняет ничего. У вас есть 4 строки стоит комментариев, которые не говорят читателю любые интересные детали. Если вы хотите поставить комментарий там, он должен что-то объяснить интересно о коде, не просто повторите, что делает код. Например:
/**
* The database user's 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 = "";
Чтобы выбрать на другом примере, посмотрите на этот комментарий:
/**
* Gets the specified connection details from this instance.
* @param boolean $show_details
* @return string The connection string.
*/
public function getConnectionString($show_details = false) {
...
Этот комментарий является хорошим началом, но оно пропускает некоторую решающую информацию: что именно делает Show_Details Parameter? Какие детали будут отсутствовать, если она не включена? Или что будет включено, когда это включено?
Комментарии не принципиально плохо, и больше комментариев не всегда хуже, чем меньше комментариев. Важно иметь правильное Комментарии!
Комментарий столько, сколько вам нужно, чтобы получить значение вашего кода. Время, которое вы получаете, если таковые имеются, не разборки комментариев перегружены болью поддержания непрозрачного кода.
, которые сказали, комментарии должны быть значимыми, и у вас есть немного больше, чем строго необходимо. Например:
/**
* The database that this instance will write to, and read from.
* @var string
*/
private $database = "";
Я задаю вопрос, добавляет ли большой комментарий здесь что-нибудь к вашему коду.
Я бы считал, что случай нелепо контрпродуктивной преждевременной микро оптимизации:
- игнорирование комментариев - это почти наименее комплексная и трудоемкая часть анализа
- , если производительность Важно, вы захотите в любом случае, вы захотите использовать сервер, который кэширует Bytecode PHP Bytecode, что делает разборные накладные расходы
- никогда не торговать ремонтопригодностью для производительности, если у вас нет жестких данных, которые доказывают, что у вас есть проблема с производительностью, и где именно она лежит