О комментариях в коде замолвите слово

    Появился пост, в комментариях к которому (какая ирония) было много мнений,
    что самый лучший код — self-documenting и все такое.

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


    В посте я кратко расскажу, как использую комментарии в своей разработке уже 10 лет и плавно затрону тему документации вообще.

    Комментарии помогают найти забытый код


    Есть у Артемия Лебедева (мастер эпатажа ИМХО) такое правило — он знает образ своего мышления. И если забыл что-то, например, где нужная фотка лежит, то знание системы категоризации своей позволяет найти быстро нужную фотку.

    То же самое и с комментариями. У меня есть проекты, которые не трогал много лет. Открываешь в IDE этот проект, вбиваешь пару слов, и находишь нужные файлы и классы без усилий. То бишь первая тема — писать, что делает хотя бы каждый файл, в самом начале. Очень экономит время поиска. А когда есть еще и тесты — поиск упрощается совсем.

    Комментарии помогают разрабатывать в IDE


    Так устроены IDE, что они держат всякие javadoc в памяти. И когда ты пишешь новый код, всплывающие подсказки очень облегчают жизнь, поясняя, что и как. Особенно когда работает над проектом команда, и ты используешь сторонние методы.

    Комментарии помогают в создании документации


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

    Документация вообще


    Мне, спустя года, стало нравится высказывание «лень — двигатель прогресса». Считаю, ленивый программист или админ — это врожденное и полезное качество.

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

    Когда мне дали несколько нагруженных проектов, где вопросы разработчиков были очень частыми, я стал применять принцип трех гвоздей. На каждый типовой вопрос после третьего обращения я писал FAQ, на каждую задачу — туториал с комментариями в коде туторила.

    Через полгода на 80% я отвечал ссылками на туториалы и FAQ и не выходил из потока, хотя количество моих подчиненных выросло на проектах от двух до пяти.

    Вывод


    Если вы работаете один, если у вас масса времени, если вы не делаете проекты в промышленном масштабе — то можно писать красивый самодокументирующийся код. Я так делал в своих поделках до поры до времени.

    Можно писать хороший читаемый код, но для восприятия проекта в целом и решения практических задач, изложенных выше, комментарии полезны.

    Если вы работаете в команде, у вас есть проекты, которые вырастут до >100,000 строк кода, и вы будете возвращаться к ним через пару лет — комментарии вам просто необходимы. Хотя бы на уровне, что делает тот или иной файл, тот или иной большой важный кусок логики.

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

    Особенно актуально после принятия проектов от нубов, которые прочитали Макконнелла про самодокументирующийся код и запомнили, что комментарии писать не надо, а все остальные рекомендации к оформлению кода и code conventions проигнорировали напрочь — или, не дай Бог, фриланс-заказ из прошлого по поддержке индусского сайта).

    А если еще при этом вы является Senior, Team Lead разработчиком, и в ваши обязанности входит еще и работа с нетехническими людьми, либо работа с новичками — то документация, наращиваемая по эволюционному принципу on-demand для повышения, так сказать, cache hit raio, станет существенной экономией вашего времени.

    Ссылки в тему
    1.There is No Such Thing as Self-Documenting Code – It’s a Myth

    2. Bloated names, and the myth of self-documenting code

    3. Intent versus action, or the myth of self-documenting code

    4. Self Documenting Code and other Myths

    Similar posts

    Ads
    AdBlock has stolen the banner, but banners are not teeth — they will be back

    More

    Comments 23

      –3
      Комментарии как документация?
      Ну да — Вы их написали и всё классно. Но код обычно меняется. И чаще всего те, кто его меняют, не будут менять комментарии. Забудут, не обтчратят внимание, поленятся. И будет у Вас нерелевантная документация в коде
        +3
        Еще быстрее устаревает обычная документация.
        Это вопрос практики :)
          +4
          Чем принципиально отличается от того, что забудут поменять ия класса или контанты? В том топик был прмер MILLISECONDS_PER_HOUR = 2*60*60*1000L. Это лишь вопрос дисциплины и ответственности и он решается другими методами.
            +7
            Если такая ситуация возникает часто — то это проблема не в комментариях, а в программистах. Ибо подобные товарищи сегодня забудут поменять комментарий, а завтра забудут проинициализировать переменную. Или еще что-нибудь забудут уже в коде. Так что это вопрос уже не в методологии оформления кода, а в уважении к товарищам по команде, которым в дальнейшем поддерживать подобный код с неактуальными либо отсутствующими комментариями.

            Лично я придерживаюсь следующего подхода:
            Когда комментарии не нужны? Когда код очевидный и самодокументируемый, по нему спокойно можно пробежать глазами, и сразу все понятно.
            Когда комментарии нужны?
            — Для автоматической генерации документации типа javadoc. Тот, кто будет читать эту документацию, не будет видеть перед глазами код, а будет видеть только документ, сгенерированый на основе комментариев. Иначе ему придется держать перед глазами еще и исходник, что сразу делает бессмысленым генерацию документации.
            — При объявлении неочевидных констант, когда для объяснения смысла константы придется делать ее имя слишком длинным.
            — Для пояснения каких-то деталей в коде, не связанных непосредственно с алгоритмом, но необходимых для адаптации к конкретному устройству или среде (например различных проверок, предположений, что вот здесь система будет вести себя определенным образом и т.п.).
            — Для пояснения неочевидных алгоритмичесуих решений. Например с целью оптимизации.

            Естественно, критерий «очевидности» у каждого свой в зависимости от опыта. Для кого-то деление побитовым сдвигом будет нуждаться в комментировании, для кого-то и сложные структуры данных и алгоритмы будут казаться очень легко читающимися и не нуждающимися в дальнейших пояснениях. Но стоит только помнить, что экономя свое время на написании комментария, ты отнимаешь его у коллеги, которому придется разбираться в твоем коде…
              –2
              чаще всего те, кто его меняют, не будут менять комментарии. Забудут, не обтчратят внимание, поленятся.
              История коммитов быстро покажет, кто будет бегать за пиццей весь следующий месяц, а кого и квартальной премии лишат :)
                0
                Ревью кода в таком случае подразумевает и ревью *docs в комментах, не так ли?
                  0
                  clang умеет проверять документацию. Хотя бы простейшие расхождения он уже будет находить.
                    0
                    Комментарий должен описывать базовые принципы работы функции/метода/поля/класса.
                    Будет очень странно если метод класса SQLTransfer.insert будет писать в файл. Как говориться, за такое руки отрывают :-)

                    И вот эти вот комментарии порой очень важны. Особенно, если программист пишет что-то совсем за облачное и далекое от стандартного. Хрен поймешь по коду потом что именно он написал.
                  +2
                  Почитал я статью, которая сподвигла вас к написанию сего поста и мне кажется вы её немного не так поняли. Как писал автор «Комментировать или не комментировать?» коментарии для документации писать надо, особено если вы хотите сделать документацию по паблик АПИ, это может стать удобно, особенно если следовать какой-нибудь структуре типо jsdoc. Однако коментировать код для «Комментарии помогают найти забытый код» звучит бредово, человек который будет работать с кодом потом, скорее всего кроме чувства недоумения ничего не успытает ибо врятли он будет искать код вашим методом, нужный код помогают искать правильная архитектура проекта и названия классов/методов/функций
                    +3
                    Сподвигли комментарии к той статье :)

                    Много в стиле — да ну нафиг, пишу без комментов и все отлично.
                    +1
                    Была неделя «Морского боя» на Хабре, теперь вероятно будет неделя «Комментарии в коде». Самым важным следствием явится то, что все будут поступать по прежнему, так как выработавшуюся за годы привычку сложно поменять.
                      +1
                      Поможет тем, у кого еще не выработались хорошие/вредные привычки.
                      +2
                      Вы, вероятно, не дочитали пост от DreamWalker. В разделе «Когда можно и прокомментировать» вроде все хорошо изложено.
                        0
                        Тот пост нормальный.
                        Комменты к нему в стиле — а зачем комменты, если в thisIsMySuperSelfdocumentingCode все понятно — и вынудили пост написать?
                        +1
                        Я так подозреваю, что тут взаимопониманию сторон мешает различие в терминологии — многие javadoc (и аналогичную incode документацию) не воспринимают как комментарии.
                          +3
                          Главное отличие вашего поста от предыдущего — у вас много комментариев и совсем нету кода. При этом половина статьи как не надо писать украшена кодом, а вторая, как надо без кода. Вы вторую часть вовсе не заметили, потому как привыкли читать только код, а на тексты избирательная слепота.
                            0
                            Тот пост нормальный.
                            Комменты к нему в стиле — а зачем комменты, если в thisIsMySuperSelfdocumentingCode все понятно — и вынудили пост написать?

                            Кстати, диагностика по постам в инете — это круче Ванги :)
                              0
                              Там был пост нормальный, но вы прореагировали только на первую часть и упустили вторую, где автор писал когда комментарии нужны.
                              >>thisIsMySuperSelfdocumentingCode
                              В оригинальном посте было про это
                              >>Когда можно и прокомментировать
                              >>Комментарии, которые повышают уровень абстракции
                              >>не всегда возможно подобрать краткие названия для классов
                                0
                                Я не очень понятно пишу :((

                                Тот пост нормальный. ВЕСЬ.

                                Моя реакция — не на пост. А на комментарии к нему.
                                Очень много было — да я вообще не пишу комменты.
                                В первом уровне, к примеру.
                                >отсутсвие коментариев оправдано если код написан людьми для людей.

                                >Мы комментируем только нетривиальные участки кода, без которых не обойтись. В остальных случаях отдается приоритет простому и читабельному коду.

                                >Хорошая статья. Для себя давно выбрала не комментировать.

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

                                Были и комменты, что комментировать код надо, и пошел холивар.

                                Я написал свое ИМХО, почему на практике комменты рулят и в каких случаях. Пишешь один — не тратишь время через год,
                                разбираясь, что и где.
                                Удобно в IDE подсказки иметь
                                Работаешь с чужим проектом — автогенерированная дока удобно, не лезя в код.

                                и т.д.
                            +2
                            Похоже, я дожил до того светлого дня, когда в программировании стало всё настолько хорошо, что пора обсуждать где нужны или не нужны комментарии, а больше и обсудить нечего
                              +1
                              Вы забыли сказать, что изначально мало кто умеет писать правильные комментарии.
                              Но к этому приходят только те, кто их не избегает.

                              Те, кто пишут «самодокументированный код», просто никогда не освоят это искусство.
                                0
                                +1000
                                0
                                Я — автор поста про комментарии. Мне бы хотелось внести несколько уточнений.
                                Я не говорил, что комментарии писать не нужно. Я говорил, что если вам удалось написать такой код, который комментариев не требует, то это просто прекрасно. Значит тут комментарий по определению не нужен — он не привнесёт в проект ничего нового. Если код без комментариев непонятен, то пожалуйста — пишите комментарии. Только вот я агитирую за то, что если код получился какой-то непонятный, то лучше бы переписать сам код, чем компенсировать его комментариями. Но если не получается — то комментируйте, хуже от этого не будет. Главное — чтобы код был читаемым.
                                Если у нас имеется плохой программист, который пишет плохой код, но держит в уме правило, что «комментарии писать нельзя», то проблема-то не в правиле. Во-первых, правило звучит несколько иначе, я об этом только что написал. Во-вторых, рассмотрим случай когда он написал свой код без комментариев и считает, что он — идеальный. Кто вам сказал, что он написал бы нормальный комментарий к этому коду? Я встречал много случаев, когда код не очень понятен, а после чтения комментариев он становится непонятным вообще. Проблема в плохих программистах, которые выдирают из хороших практик к совершенному коду (до которого им ещё далеко) по одному предложению и начинают их применять везде подряд.
                                Что касается разработки документации через комментарии (JavaDoc и тому подобные), то кто я такой, чтобы вам запрещать это делать? Это вопрос не о совершенном коде, а методологиях разработки. И да, у меня в посте есть абзац про то, что если в команде решили писать документацию через комментарии, то это ваше решение, к совершенному коду это не относится. В статье-то большей частью обсуждаются совсем другие комментарии.
                                Но немного про совершенный код всё-таки скажу. Если вы ищите методы через комментарии к ним, то, наверное, что-то у вас ни так с названиями методов. Отличный пример того, как комментариями пытаются компенсировать плохие именования. Я в своих (даже весьма больших проектах) просто набирают по несколько первых букв слов, входящих в название (совсем не обязательно всех слов) — и IDE сама находит мне все нужные классы и методы.

                                Only users with full accounts can post comments. Log in, please.