Когда пишу код для заказчика, то оставляю (как мне кажется) много комментариев, особенно если есть возможность писать их на русском. Во-первых, потому, что я в чужом проекте не навсегда и было бы правильно, чтобы в моем коде могли без проблем разобраться и без меня. Тем более, что стараюсь работать качественно, а наличие комментариев в коде -- это и есть один из критериев качества. Во-вторых, как-то получается, что мне поручают делать не самые тривиальные вещи, поэтому нелишним будет эти самые нетривиальные вещи снабдить пояснениями, в том числе и для самого себя. Проще всего это делать как раз комментариями в коде.
Когда пишу код в наш OpenSource, то так же стараюсь делать побольше комментариев. Т.к. точно знаю, что со временем они потребуются мне самому. Проверенно неоднократно. Опять же, стараюсь работать качественно, а комментарии -- это и есть один из критериев качества. Мне же потом с этим работать, поэтому не хочется лишний раз корить самого себя за небрежно выполненную работу.
Изредка приходится делать маленькие (или не очень маленькие) программки "на выброс". Буквально на один-два проверочных запуска, после чего все написанное отправляется в корзину. Вот там, как правило, вообще никаких комментариев нет. Точнее не бывало. До недавних пор.
Как раз давеча пришлось такими маленькими программками заниматься.
И вот что удивительно: после того как объем кода превысил 150-200 строк я внезапно поймал себя на том, что больше не могу без комментариев. Руки сами отказываются дописывать новые строки без предварительный поясняющих комментариев.
Объяснение нашел в том, что уже тупо старею, мозги уже не те, чуть-чуть больше деталей, и в память они не помещаются. А выход в том, чтобы писать предварительные поясняющие комментарии, к которым можно вернуться и восстановить то, что уже выпадает из уменьшающейся с возрастом оперативки... 🥴
Чтобы не быть голословным, вот эти одноразовые программулины, о которых я только что говорил. С этого все начиналось, а вот к чему в итоге пришло: тыц, тыц и тыц. Сам в шоке.
Весь этот код, по сути, одноразовый. Заливал его на github только ради простоты переноса между разными компьютерами. Ну и экспериментировать с кодом, когда он под контролем версий, таки спокойнее и удобнее.
PS. Неприятным побочным эффектом от привычки писать комментарии становится все возрастающая нетерпимость к коду без комментариев.
PPS. Самодокументирующийся код -- это миф. Возможно, фанаты сего мифа просто пока не сталкивались с более-менее сложными задачами, в которых куча неочевидных моментов и специфическим образом выбранных решений. Если эти самые моменты и решения не документировать комментариями, то код превращается, в лучшем случае, в криптограмму, на расшифровку которой требуется все больше и больше усилий по мере его сопровождения и старения. Да и само сопровождение больше напоминает передвижение по минному полю, когда не знаешь где и когда рванет. Но, в большинстве случаев, это откровенный говнокод, в который не хочется тыкать и трехметровой палкой.
PPPS. Проблема с бесполезными и тривиальными комментариями не в том, что они бесполезны. Проблема в том, что программистов не научили комментарии писать. Поэтому эти самые программисты и пишут бесполезные комментарии. Ну не умеют писать полезные и это объясняет текущее состояние дел почти на 95%.
PPPPS. Есть у меня ощущение, что в последние 15 лет программистов-то и программировать уже не учат. Что уж тут говорить про обучение написанию комментариев 🥺 ИМХО, это один из китов, на которых покоится миф о самодокументирующемся коде.
1 комментарий:
Когда смотрел на приведённый Вами отрывок кода, меня посетила мысль, что если из него убрать весь код, оставив лишь одни комментарии, код можно будет восстановить. Наверное можно сделать и наоборот, но комментарии, всё же, дают больше информации. То есть комментарии первичны, а код вторичен. Не думаю, что я первый кому пришла такая мысль, но, мне кажется, факт в том, что привалирует, и не безосновательно, подход, что код пишется в первую очередь для машин, а не для людей. Следовательно сейчас код "побеждает" комментарии. Хорошие комментарии не помогут выйграть в хакатоне, например. И вообще, что на мой взгляд прискорбно, были оставлены попытки создать язык программирования более высокого уровня. Да, по сути, как и наши предшественники, мы продолжаем программировать на ассемблере. Конечно уровень абстракции выше, но принцип остаётся неизменным - программа пишется для машины. Причём, как мне кажется, большинство программистов это устраивает и им даже в голову не приходит, что может быть по другому. Поэтому я уже перестал смотреть на новые языки программирования, коих до кучи, ибо увижу "те же яица, только в профиль". Хочется сказать: "Когда поднимите уровень абстракции - разбудите" ;)
Отправить комментарий