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