1. Не все комментарии одинаково
полезны
Анна Зайцева
web-разработчик
Anna.zaytseva@softline.ru

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

3. Одна из основных причин написания комментариев
- плохое качество кода.
$currUser = new User($userName, $userPass, 0);
$currUser = new User($userName, $userPass);
$currUser->save();

4. Классификация плохих комментариев

5. Бормотание
Комментарий есть, пользы нет.
order.default_customer_type_is_juridical = 0 ;
поумолчанию тип покупателя юридическое лицо
Комментарий, смысл которого приходится искать в других
модулях, не несет полезной информации.

6. Избыточные комментарии
Чтение такого комментария займет больше
времени, чем чтение самого кода

7. Недостоверные комментарии
Причины:
 неточно выраженная мысль;
 потеря актуальности с течением времени;
Результат:
 неверные ожидания от кода;
 неправильное использование кода;
 потеря времени на поиск источника проблемы;

8. Обязательные комментарии
 загромождают код
 распространяют недостоверную информацию
 вносят путаницу
/**
* Класс менеджер ПС
* @author Ann Zaitseva
* @since 2012-05-04
* @see RM-51854
*/
class PaymentSystemManager {

9. /**
* Город
*/
private $city
/**
* Возвращает город
*
* @return string
*/
public function getCity()
{
return $this->city;
}

10. Пересказы (переводы)
 не несут никакой дополнительной информации;
 уменьшают плотность информации;
 их никто не читает (даже сами авторы);
 часто недостоверны
* Класс менеджер покупателей
class DeliveryManager

11. Журнальные комментарии
/**
* Добавила возможность автоотправки ключей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
*/

12. /**
* @desc Ставим значение NOW(), вместо $DEFDATE = date( "Y-m-d
H:i:00" );
* Зачем вручную делать то, что должен делать MySQL и плодить
возможные ошибки?
* @see TS2898
* @author Vladimir Savenkov
*/
$DEFDATE = 'NOW()';

13. Закомментированный код
Если код не нужен, его нужно удалять!

14. Плохо подобранное название
/**
* переносит содержимое корзины от гостя
* к авторизованному пользователю
*/
public function auth {
Не трать время на написание комментария. Потрать его на написание
хорошего кода

15. Комментарии за закрывающей фигурной
скобкой.
} // end foreach
} // end getList
} // end class

16. Комментарии 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>

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

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