Комментарии 7
Всем этим массовым хабрастайл-статьям не хватает гикости (или гиковства). Получается что-то такое: ребята, надо делать то-то и то-то (мотивация), но не раскрываются все необходимые важные знания. Я, конечно, понимаю, программирование — сложная тема для разговора. Но зачем тогда статья, содержимое которой
Лично я готов погиковать на эту тему, у меня есть наработки… Например, мне тоже не нравится фраза
«хорошему коду не нужны комментарии»
Но мне эта фраза не просто не нравится, а я могу разложить по полочкам, каких комментариев будет не хватать любому, хоть самому совершенному (идеальному) коду. Могу доказать ложность утверждения, предложить методологии и шаблоны комментирования идеального кода. Более того, я тут работаю над языком комментирования (если угоден такой термин) взамен свободного комментирования. Этого не хватает статье.
Да напишите уже статью про это.)
Стоит добавить ещё, что в погоне за "самодокументирующимся кодом" рождаются монстры типа:
document.getElementById( 'close' ).addEventListener( 'click', closeCurrentPanelOnlyOneTime )Вместо:
$( '#close' ).on( 'click', ()=> panelCurrent.close() )
Согласен с вами про
«хорошему коду не нужны комментарии»
Документация функций нужна практически во всех случаях, когда код разбивается на несколько файлов, и время его разработки превышает неделю.
Документация функций и классов позволяет вернуться к старому проекту за несколько часов. Указание параметов, исключений, связанных классов ускоряет понимание роли функции в проекте.
Комментарии в самом коде я оставлю на усмотрение разработчика. Они могут быть нужны в случае for(int i = 0; i < arr.length;), где возникает вопрос, почему значение i не обновляется. Константы в коде тоже должны содержать комментарии, например значения по умолчанию и/или описание поведения при их изменении.
Таково моё субъективное мнение про комментирование, интересно узнать ваше.
Исходный код без комментариев представляет строгую информацию о том, как работает программа. При этом программа была создана по неким требованиям окружения, в которое она внедрена. Именно из окружения взята информация, почему, как и зачем, создана программа. В исходном коде информации об окружении нет. Следовательно эта информация должна быть в комментариях.
Но тут важная практическая оговорка: разработчик держит в голове все требования, которые он соблюдает в течение разработки и сопровождения кода, и эту информацию формализовать долго, сложно (=дорого). Бывает даже так: если в проект приходит новый разработчик, то он зачастую может быстро вникнуть в окружение, буквально погрузиться в него в течение часа, например, молодой человек может просто поиграть в разрабатываемую игру (погружение непосредственно в окружение). Еще бывает тезаурус разработчика не требует описания, так как разработчику по его опыту и так понятно, как работает программа в окружении.
Но в некоторых случаях, наоборот, сведения об окружении невозможно собрать, так как внедренная система работает в другом городе или даже в другой стране, или иногда внедренных систем много…
Отсюда вывод: комментировать надо окружение, но не всегда нужно описывать полностью, ибо дорого.
Хороший, плохой, злой комментарий