Комментировать или не комментировать?

    «Ясно, что на некотором уровне комментарии должны быть полезны. Думать иначе означало бы полагать, что понятность программы не зависит от того, сколько информации о ней уже известно читающему программу человеку. Б. Шейл.»
    Действующие лица:
    ФРАСИМАХ Неопытный пурист теории, который верит всему, что читает.
    КАЛЛИКЛ Закаленный в боях представитель старой школы — «настоящий»
    программист.
    ГЛАВКОН Молодой, самоуверенный, энергичный программист.
    ИСМЕНА Опытная разработчица, уставшая от громких обещаний и просто
    желающая найти несколько работающих методик.
    СОКРАТ Мудрый опытный программист.

    Мизансцена:
    Завершение ежедневного собрания группы
    — Желает ли кто-то обсудить еще что-нибудь, прежде чем мы вернемся к работе? — спрашивает Сократ.
    — Я хочу предложить стандарт комментирования для наших проектов, — говорит расимах. — Некоторые наши программисты почти не комментируют свой код, а всем известно, что код без комментариев нечитаем.
    — Ты, должно быть, еще менее опытен, чем я думал, — отвечает Калликл. — Комментарии — это академическая панацея, и любому, кто писал реальные программы, известно, что комментарии затрудняют чтение кода, а не облегчают. Естественный язык менее точен, чем Java или Visual Basic, и страдает от избыточности, тогда как операторы языков программирования лаконичны и попадают в самое яблочко. Если кто-то не может написать ясный код, разве ему удастся написать ясные комментарии? Кроме того, комментарии устаревают при изменениях кода.
    Доверяя устаревшим комментариям, ты сам себе роешь яму.

    — Полностью согласен, — вступает в разговор Главкон. — Щедро прокомментированный код читать труднее, потому что в этом случае читать приходится больше. Мало
    того, что я должен читать код, так мне нужно читать еще и кучу комментариев!
    — Подождите минутку, — вставляет свои две драхмы Йемена, ставя чашку кофе.
    — Конечно, злоупотребление комментариями возможно, но хорошие комментарии
    ценятся на вес золота. Мне приходилось сопровождать код как с комментариями,
    так и без них, и, будь у меня выбор, я бы предпочла первый вариант. Не думаю, что
    нам нужен стандарт, заставляющий писать один комментарий на каждые х строк
    кода, но побудить всех программистов комментировать код не помешает.
    — Если комментарии — пустая трата времени, почему все их используют, Калликл? — спрашивает Сократ.
    — Или потому, что таково требование, или потому, что человек прочитал где-то о
    пользе комментариев. Ни один программист, когда-либо задумавшийся об этом, не пришел к выводу, что комментарии полезны.

    — Йемена считает, что они полезны. Она уже три года сопровождает твой код без
    комментариев и чужой код с комментариями. Ее мнение ты уже слышал. Что ты
    скажешь на это?
    — Комментарии бесполезны, потому что они просто повторяют код в более многословной…
    — Подожди, — прерывает Калликла Фрасимах. — Хорошие комментарии
    не повторяют код и не объясняют его. Они поясняют его цель. Комментарии должны объяснять намерения программиста на более высоком уровне абстракции, чем код.
    — Верно, — соглашается Йемена. — Если я ищу фрагмент, который мне нужно изменить или исправить, я просматриваю комментарии. Комментарии, повторяющие код, на самом деле бесполезны, потому что все уже сказано в самом коде. Когда
    я читаю комментарии, я хочу, чтобы они напоминали оглавление книги. Комментарии должны помочь мне найти нужный раздел, а после этого я начну читать
    код. Гораздо быстрее прочитать одно предложение на обычном языке, чем анализировать 20 строк кода на языке программирования.
    Йемена наливает себе вторую чашку кофе.

    — Мне кажется, что люди, отказывающиеся писать комментарии, A) думают, что
    их код понятнее, чем мог бы быть, B) считают, что другие программисты гораздо сильнее интересуются их кодом, чем есть на самом деле, C) думают, что другие программисты умнее, чем есть на самом деле, D) ленятся или E) боятся, что
    кто-то другой узнает, как работает их код.
    — В этом смысле очень помогли бы обзоры кода, Сократ, — продолжает Йемена.
    — Если кто-то утверждает, что комментарии писать не нужно, и получает во время обзора кучу вопросов — если сразу несколько коллег спрашивают его: „Что происходит в этом фрагменте твоего кода?" — он начинает писать комментарии. Если программист не дойдет до этого сам, его руководитель сможет заставить его писать комментарии.
    — Я не утверждаю, Калликл, что ты ленишься или боишься, что кто-то другой поймет твой код. Я работала с твоим кодом и могу сказать, что ты — один из лучших
    программистов компании. Но будь чуточку добрее, а? Мне было бы легче сопровождать твой код, если бы ты писал комментарии.

    — Но это пустая трата времени, — не сдается Калликл. — Код хорошего программиста должен быть самодокументирующимся: все, что нужно знать другим программистам, должно быть в самом коде.
    — Нет! — Фрасимах вскакивает со стула. — В коде и так уже есть все, что нужно
    знать компилятору! С таким же успехом можно было бы сказать, что все, что нужно знать другим программистам, уже есть в двоичном исполняемом файле! Если
    бы мы только были достаточно умны, чтобы уметь читать его! Информации о том,
    что программист собирался сделать, в коде нет.
    Фрасимах замечает, что вскочил с места, и садится.
    — Сократ, это немыслимо. Почему мы спорим о важности комментариев? Во всех
    книгах, которые я читал, говорится, что комментарии полезны и что на них не стоит экономить. Мы зря теряем время.
    — Успокойся, Фрасимах. Спроси у Калликла, как давно он программирует.

    — Действительно, как давно, Калликл?
    — Ну, я начал с системы Акрополь IV где-то 15 лет назад. Думаю, что я стал свидетелем рождения и гибели примерно десятка крупных приложений. А еще в десятке проектов я работал над крупными компонентами. Две из этих систем включали более полумиллиона строк кода, так что я знаю, о чем говорю. Комментарии совершенно бесполезны.
    Сократ бросает взгляд на более молодого программиста.
    — Как говорит Калликл, с комментариями действительно связано много проблем,
    и ты не поймешь это, пока не приобретешь больше опыта. Если комментировать
    код неграмотно, комментарии не просто бесполезны — они вредны.
    — Они бесполезны, даже если комментировать код грамотно, — заявляет Калликл.
    — Комментарии менее точны, чем язык программирования. Лично я думаю, что
    лучше вообще их не писать.

    — Постой, — говорит Сократ. — Йемена согласна с тем, что комментарии менее
    точны, но она утверждает, что комментарии поднимают программиста на более
    высокий уровень абстракции, а все мы знаем, что абстракция — один из самых
    эффективных инструментов, имеющихся в нашем распоряжении.
    — Я с этим не согласен, — заявляет Главкон. — Нам следует концентрироваться
    не на комментариях, а на читабельности кода. При рефакторинге большинство
    моих комментариев исчезает. После рефакторинга мой код может включать 20
    или 30 вызовов методов, не нуждающихся в каких бы то ни было комментариях.
    Хороший программист способен определять цель автора по самому коду; к тому
    же какой толк в чтении о чьей-то цели, если известно, что код содержит ошибку?
    Главкон умолкает, удовлетворенный своим вкладом в беседу. Калликл кивает.
    — Похоже, вам никогда не приходилось изменять чужой код, — говорит Йемена.
    Калликл делает вид, что его очень заинтересовали плитки на потолке.

    — Почему бы вам не попробовать прочитать собственный код через шесть месяцев или год после его написания? Вы можете развивать и навык чтения кода, и навык
    его комментирования. Никто не заставляет вас выбирать что-то одно. Если вы читаете роман, вам, может, и не нужны названия глав. Но при чтении технической
    книги вам, наверное, хотелось бы иметь возможность быстро найти то, что вы ищете.
    Тогда мне не пришлось бы переходить в режим сверхсосредоточенности и читать
    сотни строк кода для нахождения двух строк, которые я хочу изменить.
    — Хорошо, я понимаю, что возможность быстрого просмотра кода была бы удобной, — говорит Главкон. Он видел некоторые из программ Исмены, и они не оставили его равнодушным. — Но как быть с другим утверждением Калликла — что
    комментарии устаревают по мере изменений кода? Я программирую лишь пару
    лет, но даже я знаю, что никто не обновляет свои комментарии.

    — Ну, и да, и нет, — говорит Йемена. — Если вы считаете комментарии неприкосновенными, а код подозрительным, у вас серьезные проблемы. На самом деле несоответствие между комментарием и кодом обычно говорит о том, что неверно
    и то, и другое. Если какие-то комментарии плохи, это не означает, что само комментирование плохо. Пойду налью себе еще чашку кофе.
    Йемена выходит из комнаты.
    — Мое главное возражение против комментариев, — заявляет Калликл, — в том,
    что они тратят ресурсы.
    — Можете ли вы предложить способ минимизации времени написания комментариев? — спрашивает Сократ.
    — Проектирование методов на псевдокоде, преобразование псевдокода в комментарии и написание соответствующего им кода, — говорит Главкон.
    — ОК, это сработает, если комментарии не будут повторять код, — утверждает Калликл.
    — Написание комментария заставляет вас лучше подумать над тем, что делает ваш
    код, — говорит Йемена, возвращаясь с новой чашкой кофе. — Если комментарии
    писать трудно, это означает, что код плох или вы недостаточно хорошо его понимаете. В обоих случаях вы должны поработать над кодом еще, так что время, потраченное на его комментирование, не пропадает — оно указывает вам на необходимую работу.
    — Хорошо, — подводит итоги Сократ. — Не думаю, что у нас остались еще вопросы. Похоже, Йемена сегодня была самой убедительной. Мы будем поощрять комментирование, но не будем относиться к нему простодушно. Мы будем выполнять
    обзоры кода, чтобы все поняли, какие комментарии на самом деле полезны. Если
    у вас возникнут проблемы с пониманием кода другого программиста, подскажите ему, как он может его улучшить.

    Стив Макконнелд
    Ads
    AdBlock has stolen the banner, but banners are not teeth — they will be back

    More

    Comments 12

      0
      со своей "колокольни" могу сказать, что комментарии в коде если и нужны, то только, как пояснение каких-то хаков, без которых не обойтись

      подавляющую массу кода можно сделать самодокументируемой путем рефакторинга

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

      в свое время мне нравились такие вещи, как Doxygen
        0
        Я за Калликла! Крайне предпочтительно создавать код не нуждающийся в комментариях. Давать «говорящие» имена классам, методам и переменным. А комментариями снабжать только крайне неочевидные фрагменты кода, когда стремясь за производительностью либо какими другими целями приходится отступать от принципа очевидности кода.
          +4
          Первое, что хотелось написать - Ниасилил!
          Сдержался, да. С трудом. :-)

          1. Притча, как и программный метод, должна быть недлинной. Строк 20-30. Ну ладно - для эстетов - 40-50 :-)

          2. Имена действующих лиц, как и названия переменных, не заумными, а понятными нашему человеку. Ну скажем так:

          ФРАСИМАХ = Салага.
          КАЛЛИКЛ = ОпытныйПерец.
          ГЛАВКОН = Выскочка.
          ИСМЕНА = ПрикладнаяТётка.
          СОКРАТ = МудрыйПряник.

          ну и так далее...

          3. Комментарии бывают тактические и стратегические.

          Тактические, могут быть скомпенсированы грамотными названиями методов и переменных. Нужны в непростых местах (типа сдвига третьего бита влево на 17 позиций, какого хрена...).

          Стратегические - желательны всегда. Для чего это всё нужно, какой алгоритм, подход, патерны запользованы. Хотя бы несколько строк на метод.

          ну где-то во-так видимо....
            0
            комментарии нужны, комментарии важны! (:
              0
              Не то что бы краткость всегда является сестрой таланта, но в вашем случае стоит задуматься.
              Помнится изначально у вас было желание типа выкладывать короткие выжимки из СС. А теперь получается вы пишете, "разливаясь по древу", еще больше чем в СС.

              Это не выжимки а наоборот раздувание. Такими темпами СС из 900 страничного талмуда превратится в 9000ный ...

              Имхо еще стоит задуматься о стиле изложения. Диалоги это конечно забавно, но не в технической статье, хорошо еще что у вас компилятор с IDE не разговаривают, такой бы сюрр был...
                0
                Небольшой пардон - это выдержка из самого Макконела =). Отписал комментарий и решил листануть СС - я этот кусок в свое время пропустил, именно потому что посчитал бредовым.

                В общем суть мнения от этого не меняется - имхо если хотите донести СС до тех кто не осилил оригинал - пишите выжимки идей, вряд ли кто захочет осиливать это на хабре пусть даже и перепечатанное.

                А вообще по-моему неблагодарное это дело, "каждый программист должен сам прийти к этой книге" ;)
                  0
                  Следующим шагом хочу выложить именно тезисы (их будет много) об архитектуре. Насчет стиля - хочу понять, какой народу ближе всего.
                    0
                    А оно надо ? Просто имхо вы пытаетесь людям объяснить на пальцах то, к чему надоидти практикой. Вот если бы мне начали 3 года назад рассказывать макконела - я бы сказал - интересно но много и мутно. Теперь же я понимаю то, ПОЧЕМУ надо делать как он пишет, а не КАК надо делать.

                    Знание КАК без ПОЧЕМУ - не имеет смысла, потому что оно или забывается, или воспитывается "культ Карго" (погуглите, если интересно). А ПОЧЕМУ объяснить нельзя, к этому надо прийти. Я тоже думал что можно учиться на теории и чужих ошибках. Проблема в том, что чужие ошибки не запоминаются. А вот свои - еще как.
                      0
                      Ваш опыт - это не опыт других людей.
                      У меня лично есть несколько знакомых, которые не берутся читать эту книгу из-за объема. Если она будет изложена в тезисах - им будет легче. Уверен, таких немало.
                        0
                        Эти тезисы у людей мало отложатся.
                        Хотите расскажу как я ее прочитал ( подразумевается ответ - да =) ):
                        Я СС читал в общей сумме наверное 1.5 года. Сначала эта книжка лежала у меня на тумбочке, мозолила глаза. Месяца 3 лежала, надоело. Потом я привез ее домой, положил в неудобное место, она там мешалась еще месяца 2. Будучи в хреновом настроении, я ее открыл, прочитал начало, и закрыл. Переложил на удобное, но видное место, т.е. она не мешала но мозолили глаза. Начал читать понемногу и параллельно с этим серьезно "увяз" в новом проекте, и стал пытаться на практике применять прочитанное. Потихоньку, глядя на результаты проекта - начал читать все внимательней, подмечать нюансы, акцентировать внимание на том, что я сделал не так, как написано, и почему я это сделал не так (не только от незнания). А книга мне помогала разъяснять - почему так делать не стоит Вот так и осилил.

                        Важен первый шаг, как говорят - главное начать.
                0
                Статья хорошая. Но с абзацами и разделением реплик что не то. Читается с трудом.
                  +1
                  потдерживаю Steamus и kivsiak!
                  ей богу переписали бы по человечески, на самом деле если напрячься можно понять, что хорошая и полезная статья, но нечитаемые имена (и не совпадаюшие в начальном описании и тексте ИСМЕНА!=Йемена), сваленый в кучу текст и т.п. убивают всякое желание читать

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