Анна Зайцева

web-разработчик

Anna.zaytseva@softline.ru

Не все комментарии одинаково полезны

Идеальный код не требует комментариевОн самодокументируем

Одна из основных причин написания комментариев - плохое качество кода.

$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. svetlanaf@softline.ru * @since 2008.02.18 * * * Добавил возможность сортировки, кликая на название столбцов * * @author Виталий Попов vitaliypop@softline.ru * @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>

Единственный источник действительно достоверной информации - код.

Не комментируйте плохой код - перепишите его.

Если написания комментария не избежать, не забывайте, что единственная цель комментария - давать ДОПОЛНИТЕЛЬНУЮ и НУЖНУЮ информацию. Если комментарий не приближает нас к этой цели, в нем нет смысла.

Комментарий не должен вводить в заблуждение. Если пишете комментарий, напишите самый понятный

Нужно всегда помнить, что все написанные комментарии в дальнейшем придется сопровождать, иначе они потеряют

актуальность и будут вводить в заблуждение