Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

484 views

Published on

  • Be the first to comment

  • Be the first to like this

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

  1. 1. Не все комментарии одинаково полезныАнна Зайцеваweb-разработчикAnna.zaytseva@softline.ru
  2. 2. Идеальный код не требует комментариев Он самодокументируем
  3. 3. Одна из основных причин написания комментариев- плохое качество кода.$currUser = new User($userName, $userPass, 0);$currUser = new User($userName, $userPass);$currUser->save();
  4. 4. Классификация плохих комментариев
  5. 5. БормотаниеКомментарий есть, пользы нет.order.default_customer_type_is_juridical = 0 ;поумолчанию тип покупателя юридическое лицоКомментарий, смысл которого приходится искать в другихмодулях, не несет полезной информации.
  6. 6. Избыточные комментарииЧтение такого комментария займет больше времени, чем чтение самого кода
  7. 7. Недостоверные комментарииПричины: неточно выраженная мысль; потеря актуальности с течением времени;Результат: неверные ожидания от кода; неправильное использование кода; потеря времени на поиск источника проблемы;
  8. 8. Обязательные комментарии загромождают код распространяют недостоверную информацию вносят путаницу/** * Класс менеджер ПС * @author Ann Zaitseva * @since 2012-05-04 * @see RM-51854 */class PaymentSystemManager {
  9. 9. /** * Город */private $city/** * Возвращает город * * @return string */ public function getCity() { return $this->city; }
  10. 10. Пересказы (переводы) не несут никакой дополнительной информации; уменьшают плотность информации; их никто не читает (даже сами авторы); часто недостоверны* Класс менеджер покупателейclass DeliveryManager
  11. 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. 12. /*** @desc Ставим значение NOW(), вместо $DEFDATE = date( "Y-m-d H:i:00" );* Зачем вручную делать то, что должен делать MySQL и плодить возможные ошибки?* @see TS2898* @author Vladimir Savenkov*/$DEFDATE = NOW();
  13. 13. Закомментированный код Если код не нужен, его нужно удалять!
  14. 14. Плохо подобранное название/** * переносит содержимое корзины от гостя * к авторизованному пользователю */public function auth {Не трать время на написание комментария. Потрать его на написаниехорошего кода
  15. 15. Комментарии за закрывающей фигурнойскобкой. } // end foreach } // end getList} // end class
  16. 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. 17.  Единственный источник действительно достоверной информации - код. Не комментируйте плохой код - перепишите его. Если написания комментария не избежать, не забывайте, что единственная цель комментария - давать ДОПОЛНИТЕЛЬНУЮ и НУЖНУЮ информацию. Если комментарий не приближает нас к этой цели, в нем нет смысла. Комментарий не должен вводить в заблуждение. Если пишете комментарий, напишите самый понятный
  18. 18. Нужно всегда помнить, что все написанные комментарии в дальнейшем придется сопровождать, иначе они потеряют актуальность и будут вводить в заблуждение

×