Pull to refresh

Comments 7

Извините, оформлена очередная статья в массовом стиле хабра. Картинка для привлечения внимания, кнопка «Айда по кат! Поехали!».
Всем этим массовым хабрастайл-статьям не хватает гикости (или гиковства). Получается что-то такое: ребята, надо делать то-то и то-то (мотивация), но не раскрываются все необходимые важные знания. Я, конечно, понимаю, программирование — сложная тема для разговора. Но зачем тогда статья, содержимое которой вода и так понятно всем?

Лично я готов погиковать на эту тему, у меня есть наработки… Например, мне тоже не нравится фраза

«хорошему коду не нужны комментарии»


Но мне эта фраза не просто не нравится, а я могу разложить по полочкам, каких комментариев будет не хватать любому, хоть самому совершенному (идеальному) коду. Могу доказать ложность утверждения, предложить методологии и шаблоны комментирования идеального кода. Более того, я тут работаю над языком комментирования (если угоден такой термин) взамен свободного комментирования. Этого не хватает статье.

Да напишите уже статью про это.)


Стоит добавить ещё, что в погоне за "самодокументирующимся кодом" рождаются монстры типа:


document.getElementById( 'close' ).addEventListener( 'click', closeCurrentPanelOnlyOneTime )

Вместо:


$( '#close' ).on( 'click', ()=> panelCurrent.close() )

Так же как и closeCurrentPanelOnlyOneTimeAndDoesNotCreateNewPanelIfNoOneExistsAndFiresEventAboutPanelClosingOnlyWhenAnyPanelReallyBeClosed. Не надо всю документацию совать в имя функции, лишь бы избавиться от комментариев.

Согласен с вами про


«хорошему коду не нужны комментарии»

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


Документация функций и классов позволяет вернуться к старому проекту за несколько часов. Указание параметов, исключений, связанных классов ускоряет понимание роли функции в проекте.


Комментарии в самом коде я оставлю на усмотрение разработчика. Они могут быть нужны в случае for(int i = 0; i < arr.length;), где возникает вопрос, почему значение i не обновляется. Константы в коде тоже должны содержать комментарии, например значения по умолчанию и/или описание поведения при их изменении.


Таково моё субъективное мнение про комментирование, интересно узнать ваше.

Если кратко, то так:
Исходный код без комментариев представляет строгую информацию о том, как работает программа. При этом программа была создана по неким требованиям окружения, в которое она внедрена. Именно из окружения взята информация, почему, как и зачем, создана программа. В исходном коде информации об окружении нет. Следовательно эта информация должна быть в комментариях.
Но тут важная практическая оговорка: разработчик держит в голове все требования, которые он соблюдает в течение разработки и сопровождения кода, и эту информацию формализовать долго, сложно (=дорого). Бывает даже так: если в проект приходит новый разработчик, то он зачастую может быстро вникнуть в окружение, буквально погрузиться в него в течение часа, например, молодой человек может просто поиграть в разрабатываемую игру (погружение непосредственно в окружение). Еще бывает тезаурус разработчика не требует описания, так как разработчику по его опыту и так понятно, как работает программа в окружении.
Но в некоторых случаях, наоборот, сведения об окружении невозможно собрать, так как внедренная система работает в другом городе или даже в другой стране, или иногда внедренных систем много…
Отсюда вывод: комментировать надо окружение, но не всегда нужно описывать полностью, ибо дорого.
Статья не привносит ничего нового, как мне кажется, для человека, который работает в команде over, скажем, 1.5 года, но шибко полезна для тех, кто только вливается в командную работу. Не так-то просто объяснить джуну, который искренне радуется тому, что победил сложную логику изящным решением, что комментарий должен быть сух и безэмоционален. Хотя бы для того, чтобы выжатый поиском багов коллега не тратил время на поиск по ключевым словам, которые были заменены сленговыми искажениями, дабы передать в комментарии дух победы и энтузиазма.
Sign up to leave a comment.

Articles