не все комментарии одинаково полезны
Click here to load reader
Transcript of не все комментарии одинаково полезны
Идеальный код не требует комментариевОн самодокументируем
Одна из основных причин написания комментариев - плохое качество кода.
$currUser = new User($userName, $userPass, 0);
$currUser = new User($userName, $userPass);$currUser->save();
Классификация плохих комментариев
Бормотание
Комментарий есть, пользы нет.
order.default_customer_type_is_juridical = 0 ; поумолчанию тип покупателя юридическое лицо
Комментарий, смысл которого приходится искать в других модулях, не несет полезной информации.
Избыточные комментарии
Чтение такого комментария займет больше времени, чем чтение самого кода
Причины: неточно выраженная мысль; потеря актуальности с течением времени;
Результат: неверные ожидания от кода; неправильное использование кода; потеря времени на поиск источника проблемы;
Недостоверные комментарии
загромождают код распространяют недостоверную информацию вносят путаницу
Обязательные комментарии
/** * Класс менеджер ПС * @author Ann Zaitseva * @since 2012-05-04 * @see RM-51854 */class PaymentSystemManager {
/** * Город */private $city
/** * Возвращает город * * @return string */ public function getCity() { return $this->city; }
Пересказы (переводы)
не несут никакой дополнительной информации; уменьшают плотность информации; их никто не читает (даже сами авторы); часто недостоверны
* Класс менеджер покупателейclass DeliveryManager
Журнальные комментарии/** * Добавила возможность автоотправки ключейorg.10354. (action = editversion, updateversion) * @author Svetlana F. [email protected] * @since 2008.02.18 * * * Добавил возможность сортировки, кликая на название столбцов * * @author Виталий Попов [email protected] * @since 15.04.2008 * ** Запрет на сортировку скриншотов * * @author Yegor Lukash * @since 03.06.2010 * @seeRM-4641 */
/*** @desc Ставим значение NOW(), вместо $DEFDATE = date( "Y-m-d
H:i:00" );* Зачем вручную делать то, что должен делать MySQL и плодить
возможные ошибки?* @see TS2898* @author Vladimir Savenkov*/$DEFDATE = 'NOW()';
Закомментированный код
Если код не нужен, его нужно удалять!
Плохо подобранное название/** * переносит содержимое корзины от гостя * к авторизованному пользователю */public function auth {
Не трать время на написание комментария. Потрать его на написание хорошего кода
Комментарии за закрывающей фигурной скобкой.
} // end foreach } // end getList} // end class
Комментарии HTML
*<ul> * <li>ESlMailingType::SpecialOffers - Специальные акции и скидки Allsoft</li> * <li>ESlMailingType::NewPrograms - Новые поступления</li> * <li>ESlMailingType::ForDealers - Для дилеров и корпоративных клиентов</li> * <li>ESlMailingType::News - Новости магазина и мира программного обеспечения</li> * </ul> * <code> * $oMailingService = new CSlMailingService(); * $oMailingService->getMailingByType(ESlMailingType::SpecialOffers)->subscribe($aParams); * </code>
Единственный источник действительно достоверной информации - код.
Не комментируйте плохой код - перепишите его.
Если написания комментария не избежать, не забывайте, что единственная цель комментария - давать ДОПОЛНИТЕЛЬНУЮ и НУЖНУЮ информацию. Если комментарий не приближает нас к этой цели, в нем нет смысла.
Комментарий не должен вводить в заблуждение. Если пишете комментарий, напишите самый понятный
Нужно всегда помнить, что все написанные комментарии в дальнейшем придется сопровождать, иначе они потеряют
актуальность и будут вводить в заблуждение