?

Log in

No account? Create an account
   Journal    Friends    Archive    Profile    Memories
 

Комментарии - morfizm


Jan. 28th, 2015 12:50 pm Комментарии

http://fearless-cat.livejournal.com/235261.html?thread=4171517#t4171517

Люди всерьёз считают, что писать говнокод это хорошо, потому что нужно лепить много комментариев, объясняющих говнокод, и типа так их "в заграничных университетах учат". Надо это менять. Я очень надеюсь, что те из вас, кто преподают в университетах, не учат людей писать лишние комментарии.

Привожу копию моего мнения про комментарии:

Правильно примерно так:
1. Комментарии нужны для архитектурных вещей (style guidelines, описание компонент и high level взаимодействий).
2. Комментарии (докстринги) нужны для APIs, с объяснением параметров, возвращаемых значений и побочных эффектов, в сложных случаях с примерами использования.
3. Комментарии нужны в неочевидных хаках.
4. Комментарии нужны в сложных алгоритмах.
Важно: комментарии *вредны* во всех остальных случаях.

Понятно, что 3 - нежелательно, редко и временно.
4 - вопреки распространённому мнению - встречается в жизни чрезвычайно редко. Например, если вы действительно пишите системного уровня библиотеку или ваш продукт super low latency (напр., оптимизированная 3D-игра или продукт для high frequency trading).

Плохие комментарии чаще всего ставят рядом с плохим кодом. Да, без комментариев было бы ещё менее понятно, но комментарии - неправильное решение. Правильное решение - переписать код таким образом, чтобы он был self-documenting (что чаще всего означает проще, структурнее и с хорошим покрытием юнит-тестами, служащими также в целях документации).

Почему лишние комментарии вредны:
*) Комментарии читаются в разы медленнее кода. Мысленно парсить естественный язык сложнее, чем парсить формальный.
*) В комментариях могут быть баги, ни чуть не менее опасные, чем баги в коде.
*) Баги в комментариях почти неизбежны со временем (комментарии "протухают") и от них трудно защититься - комментарии невозможно покрыть юнит-тестами.

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

77 comments - Leave a commentPrevious Entry Share Next Entry

Comments:

From:birdwatcher
Date:January 28th, 2015 09:11 pm (UTC)
(Link)
int i=1; // иначе не будет работать, уже пробовали
From:morfizm
Date:January 28th, 2015 09:12 pm (UTC)
(Link)
"3. Комментарии нужны в неочевидных хаках."
From:psilogic
Date:January 28th, 2015 09:17 pm (UTC)
(Link)
[ Мысленно парсить естественный язык сложнее, чем парсить формальный. ]

да ладно???

в остальном согласен

+ коменты все-таки добавляют строк текста, что в свою очередь провоцирует лишнее листание

From:archaicos
Date:January 29th, 2015 10:43 am (UTC)
(Link)
Написать понятный коллеге комментарий тоже не самое простое дело, как показывает практика.
From:me_milady
Date:January 28th, 2015 09:26 pm (UTC)
(Link)
Насколько я знаю, есть две весомые книги, признаваемые профессионалами, которые говорят как надо и как не надо писать код:
1) книга Steve McConnell "Code Complete"
2) книга "Clean Code: A Handbook of Agile Software Craftsmanship" от Robert C.Martin
Обе из них говорят то же что говоришь ты. Поэтому те кто не согласен пусть сначала прочитают эти обе книги.
From:morfizm
Date:January 29th, 2015 10:50 am (UTC)
(Link)
О, спасибо, что вспомнила эти книжки. Вторую я не читал, надо будет посмотреть.
From:rezkiy
Date:January 28th, 2015 10:25 pm (UTC)
(Link)
дык. Комментарии нужны в неочевидных случаях. Будь то хаки или сложные алги.

Если их, неочевидных случаев то есть, много, то с кодом что-то не так.

Да, и баги в комментариях действительно бывают ужасны.
Я не согласен с тем, что комментарии читаются медленнее кода.
From:archaicos
Date:January 29th, 2015 10:41 am (UTC)
(Link)
Как сейчас помню некоторые кусочки кода из нашего общего прошлого. Читаешь в кометах всякие фразочки с twizzle, zip, or all hell will break lose и ничерта не понимаешь, ни из кода, ни из сопутствующего комментария. К последнему ещё нужно прилагать личный словарик идиом аффтара. :)
From:morfizm
Date:January 29th, 2015 10:51 am (UTC)
(Link)
Спасибо! Я там чуть выше ответил подробно про чтение комментариев vs кода.
From:l_sylvanas
Date:January 29th, 2015 04:12 am (UTC)
(Link)
Я бы не обобщала так про "зарубежные университеты" :). А теперь сама немедленно обобщу: во-первых, там не учат перлу (может быть, можно встретить примеры, связанные с перлом, в каком-нибудь курсе про разные типы языков программирования), во-вторых, разумеется, насчет комментариев подход приблизительно такой, как ты говоришь. Ну, в моем зарубежном университете :).
From:morfizm
Date:January 29th, 2015 10:53 am (UTC)
(Link)
OK, спасибо за data point! :)

По поводу Перла - я, честно, видел примеры читаемого перла с юнит тестами. Один раз в жизни. Я даже модифицировал этот код. Даже в случае такого замечательного качественного кода, это всё равно заняло мне примерно втрое больше времени, чем если бы это был C++ or Python. Но в подавляющем большинстве случаев Перл либо нечитаем, либо представляет из себя нечто вроде "чуть продвинутого shell-скрипта".
From:archaicos
Date:January 29th, 2015 10:47 am (UTC)
(Link)
Хорошо пишешь, правильно, мудрые товарищи в книгах подобное тоже пишут (парочку таких книг упоминули выше).

Беда в том, что ты регулярно попадаешь в проект, где всё сделано не так, где нужных комментариев нет, где какие-то устарели, а какие-то просто не понятны без личного словаря идиом автора комментария. :)
From:morfizm
Date:January 29th, 2015 10:55 am (UTC)
(Link)
Спасибо. Устаревшие комментарии надо безжалостно уничтожать. Я это делаю без малейшего зазрения совести. Кому надо "для истории" - пусть в file history копаются. Непонятные комментарии уничтожать сложнее - всё время думаешь, что вдруг они непонятны только тебе, потому что ты такой идиот, а остальные засмеют? Но их всё равно надо уничтожать и заменять на понятные, а лучше переписывать код, чтобы был читаемый без комментариев.
From:ermouth
Date:January 29th, 2015 03:22 pm (UTC)
(Link)
Вот эта картинка под какой случай подходит?


Тут смысл такой, что это единственный пограничный случай, когда пользователь, имеющий разрешение на чтение, может в документ писать. Это контринтуитивно и неожиданно, но железно логично.

Это не хак, это не API.

Поэтому имхо просится п5 – обработчики сложных пограничных случаев нужно комментить обязательно. Читая код просто так, даже понимая контекст, ты можешь запросто такое пропустить – просто потому, что там очень неожиданное поведение в одном единственном случае.
From:psilogic
Date:January 29th, 2015 04:02 pm (UTC)
(Link)
это хак

тут понятия "чтение"/"запись" для пользователя и для doc-а разные, соответственно приходится извращаться, чтобы оправдать отсутствие третьего промежуточного состояния (когда можно писать только некоторые поля)