Как развивались комментарии к коду с 1940-х до 2020 года

А никак они не развивались. С самых первых языков программирования и по сей день комментарии коду — это всего лишь статичный текст (за некоторыми исключениями, о которых я расскажу).

image

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

Для начала, пару абзацев посвятим теме заголовка данной статьи. Да потому что толком-то и нету этой истории развития, так что можете назвать заголовок провокационным. Небольшой дисклеймер: сфера моих знаний ограничивается (по убыванию в опыте) этими языками: большой опыт: TS, JS, Rust, средний: PHP, C++, маленький: Go, Java.

Итак, всё что у нас есть это: заброшенный и глючный JSDoc, окончательно почивший в эру TypeScript, кстати для которого есть не менее глючный и заброшенный TSDoc. Для PHP существует PHPDoc, который был слабо полезным когда я кодил на этом языке. Каюсь, в C++ у меня самый маленький опыт, поэтому не слышал ни о чём подобном, а найденный в гугле CppDoc ничего кроме грустной усмешки не вызывает. Наиболее развитый в этом плане у нас, как всегда Rust. В нём есть отличная система RustDoc, но к сожалению не всегда эргономичная и всё еще слабо поддерживаемая IDE.

Таким образом, в целом картина довольно печальная, и инфраструктура комментариев вокруг кода не изменилась с самого начала истории программирования. Комментарии выглядят так же как и 90 лет назад в условном Планкалкюле, как в ассемблерном коде компьютера лунного модуля Аполло-11.

image
(фото с сайта shopify.com)

С историей покончили. Теперь, что плохого в том, что комментарии — это всего лишь статичный текст? Разве статичный текст уже не идеален и в нем что-то можно улучшить? Понапридумывали какие-то Гипертексты и HTML, Интернет целый вокруг этого. Да кому это всё надо? Что такого трудного в том чтобы вручную набирать URL-ы? Совсем обленились миллениалы.

Конечно же это был сарказм. Но какое дело Гипертекст имеет к комментариям к коду? Давайте подумаем, какие проблемы решил Гипертекст и есть ли какие-то схожие проблемы при использовании комментариев к коду?

Итак, гипертекст превратил статичный текст в текст с Гиперссылками. Легче всего понять пользу этого читая статью в Википедии. Например про Большой адронный коллайдер. Начав читать статью, большинство людей еще поймет что такое протоны и ионы, если не пропускали уроки физики. Но тут появляется слово «Адрон». Что это такое и откуда читателю узнать об этом? Если бы это был статический текст, то выхода особо бы не было, кроме как найти где-то (в библиотеке?) другой текст где написано что такое Адрон. Но слава богу это не так, и мы можем просто кликнуть по Гиперссылке.

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

/**
 * irq_cpu_rmap_notify - callback for IRQ subsystem when IRQ affinity updated
 * @notify: struct irq_affinity_notify passed by irq/manage.c
 * @mask: cpu mask for new SMP affinity
 *
 * This is executed in workqueue context.
 */
static void
irq_cpu_rmap_notify(/* не важно */)
{
/* не важно */
}


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

Что еще за IRQ? Вы даже малейшего представления не имеете что это такое. Какие дальше действия? Обращаться и отвлекать более опытных коллег? Можно конечно, но не очень хочется. Или они в отпуске. Искать по коду? Вы найдёте тысячи упоминаний этой аббревиатуры, и это повергнет вас в депрессию. Ну хорошо, допустим вы перерыли половину кодовой базы и нашли вроде бы объяснение того что же этот IRQ значит. Но бывает и так, что это объяснение к другой аббревиатуре IRQ, имеющей совершенно другой смысл! Ну хорошо, последний случай довольно редкий, но всё же.

А что если бы вы нажали на слово IRQ и чудесным образом, ваш IDE перенёс бы вас к месту определения этой аббревиатуры? Было бы здорово, правда? И к тому же достаточно просто, это не сложнее Гипертекста. Так почему же в 2020 году программисты себе не сделают такого инструмента? Я бы выделил и капсом и жирным предыдущее предложение. Причина этого для меня большая загадка. Возможно такие есть для других IDE, но я ничего не нашел для VSCode. Поэтому я сделал такое расширение сам. Приглашаю вас потестить и высказать своё мнение.

Но продолжим.

При чтении фрагмента кода, приведённого выше, а точнее комментария, вопросы возникают практически через каждое слово. Например где находится эта структура irq_affinity_notify? Или почему в 2020 году я не могу нажать на irq/manage.c чтобы IDE покорно и быстро перенесла меня к этому файлу? Это тоже для меня великая загадка. Поэтому в моём расширении первое уже решено, но пока только для JavaScript и TypeScript (следующие: C/C++, Rust, Java, Go), а второе как менее значимое будет также решено, но чуть позже.

Не хочу утомлять вас далее кучей текста, поэтому просто вставлю гифку с еще парой примеров работы:

habr1.gif

Очень боюсь критики и токсичных комментариев, но еще больше хочу узнать что вы об этом думаете?
AdBlock похитил этот баннер, но баннеры не зубы — отрастут

Подробнее
Реклама

Комментарии 26

    0
    Так почему же в 2020 году программисты себе не сделают такого инструмента?

    Если бы я был настолько же мотивирован как и Вы я бы сел и написал нужный код, но судя по тому что вы этого не сделали, Вам оно не особо то и нужно .


    Я сейчас серьезно.
    Когда мне понадобился переход к определению функции в редакторе mcedit я просто сел и написал его.

      +2
      Вы серьезно это написали? Простите, может я не понял вас, но там же буквально через 2 предложения написано что я как раз и сделал необходимое расширение для IDE?
        +5
        Дочитал, до конца после вашего комментария. Мой косяк, признаю не увидел.
        Всю статью Вы рассказывали о том, что всё плохо и в мире сплошная несправедливость и эта фраза была для меня последней каплей, я написал коммент и закрыл статью. Ещё раз прошу за это прощения. Это было неправильно. Лишь замечу что если бы статья в начале бы имела намек на то, что Вы написали некий инструмент и что Вас к этому сподвигло читать было бы проще.
        Ведь контента так много а времени так мало что вольно или невольно приходится думать с меня хватит, или а вау круто что уже конец!?
          +1
          Бывает, все мы люди :) Спасибо вам большое.
      +3

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

        +2

        Меня лично всегда удивляло, что xml комментарии в C# даже Visual Studio не отображает "красиво", когда смотришь на сам код метода:


        ///<summary>Adds two integers and return the result</summary>
         ///<returns>the difference between the two operands</returns>
         static int Add(int operand1, int operand2)
         {
           return operand1 + operand2;
         }

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

          +3
          ИМХО, основное требование к тексту программы, включая и комментарии, это то, чтобы его можно бы было редактиворвать в любом текстовом редакторе, начиная с какого-нибудь ed или vi и на любом железе, в том числе дистанционно. Поэтому закладываться на IDE и воротить что-то сложное в комментах не нужно и вредно.
            0
            Ну, такое себе требование. Ну ладно vi, его фанаты обмазывают толстым слоем клавиатурной магии, но мне трудно представить реальный use-case использования ed.
            Править сырцы на продакшн сервере на марсоходе с пингом 15 минут? Мсье знает толк.
            В конце концов, ничего не мешает базировать код на html или xml, которые при большом желании таки можно править хоть и ed-ом.
              +2
              Ну не знаю. Я вообще уже не представляю современную разработку сложных проектов без качественных инструментов IDE.

              Ну а потом, предложенный в статье способ нотации может приносить пользу в абсолютно любом текстовом редакторе, просто в VSCode будут дополнительные удобства. Например, если обозначать определение какого-то термина как предложено (например "@IRQ"), то его можно быстро найти из любого места проекта простым поиском, хоть grep-ом. Если же не обозначать так определение, то набрав в поиске «IRQ», гарантированно получим десятки, сотни результатов поиска.
                +1
                Я вообще уже не представляю современную разработку сложных проектов без качественных инструментов IDE.

                А я вот ровно наоборот — чем больше опыта, тем меньше IDE. Я последовательно поотключал автодополнение, подсказки из документации, детектор ошибок… Из всего зоопарка пока выжила только подсветка синтаксиса. И это такое наслаждение, прямо сродни просветлению: ничего не скачет, не прыгает, не возникает, не пропадает — набираешь код и ничто не отвлекает. Продуктивность выросла если не в разы, то уж вдвое — точно.

              +4
              Совсем обленились миллениалы!
                0

                Взгляните на doxygen. Не знаю как с Rust (там вроде неплохой генератор), но гошную недоделку уделывает на раз.
                По поводу плагина не уверен, но для Emacs, возможно, уже есть такой. Вообще, польза от него сомнительная. Лично мне не лень переключиться на браузер и вбить незнакомый термин руками. А если, например, я открою исходник в vi или mcedit для быстрого патча пользы вообще ноль.

                  0
                  Это хорошо конечно, если есть определение в интернете. Но тут не совсем, не только про это. В больших проектах появляются свои абстракции, и абстракции на абстракциями. Это не хорошо, но иногда никуда не деться от этого. И вот в этом случае, вы не сможете найти в сети концепцию, которая существует только в пределах вашего проекта.
                  0
                  VS + Visual Assist позволяют перейти к определению символа, упомянутого в комментарии, а также при рефакторинге-ренейминге его там же показывает в списке на переименование (правда со снятой галочкой по умолчанию). VA ещё хэштеги в комментах поддерживает, максимально простого и нативного написания: // #hashtagName и возможно ещё что-то из этой серии, сильно не вникал.

                  Насчет извращений с гиперссылками и прочим мета-тегам для комментариев, имхо затея не сильно жизнеспособная по ряду очевидных причин, впрочем сами наверное поймете через полгода использования (по своему опыту). Ну самое очевидное, если видите какую-то простую идею, которая на вид крайне полезна, но никто из миллиона хомячков ей не пользуется, скорее всего идея не очень, ну или вы очень уникальный и вам как раз зайдет.
                    +1
                    А что если бы вы нажали на слово IRQ и чудесным образом, ваш IDE перенёс бы вас к месту определения этой аббревиатуры?

                    Мне сразу вспомнились see и link из javadoc, VS code сейчас проверять не буду, но идея замечательно по ним навигирует. А конструкции типа
                    /** 
                    * @see <a href="URL#value">label</a>"
                    

                    позволяют ссылать и на внешние адреса.
                      0

                      Для linux kernel, все перечисленное отлично работает в vim+ctags. Для C++ правда уже не так хорошо, так как не понимает контекст.

                        +1
                        Я никогда не забуду, когда в начале 2000х мне попали напечатанные исходные коды прошивки контроллера НЖМД для компьютеров БК00010(-01)/БК11М.
                        Это было 40 листов ассемблерных команд где было прокомментирована абсолютно ВСЕ строки содержащие инструкции. Ни до, ни после я такого не видел ни когда.
                          0
                          По большей части вообще не люблю комментариев, за исключением, почему очевидное решение не сработает. Что странно, но видимо трех лет кодинга мало. Больше не люблю когда комментариев слишком много или они слишком подробные.

                          Друг помни если твой комментарий сложнее чем код, который он объясняет, то это плохой комментарий.

                          Для примера с ценой, максимум что я бы написал:
                          const price = 150 // копеек


                          Комментарий в стиле delete медленнее чем undefined — убрал бы совсем. Причина проста, эта информация, в грядущем, может не быть актуальной. Пример, только сегодня выяснял почему иногда в jQ сначала пишут .hasClass потом .removeClass, оказалось раньше из-за переприсваивания строки классов: className = className.replace(" " + classNames[c] + " ", " "); браузер пытался перестроить элемент даже если список классов не менялся (возможно нет, браузеры тоже умные бывают), сейчас перед присваиванием проверяется что список не равен предыдущему, и хак на скорость — неактуален.

                          Ваши хаки на проект собирайте отдельно, и не стоит слепо их таскать за собой)
                            0
                            Дело в том, что часто нужно пояснять для коллег, настоящих и будущих, а также для будущего себя, почему было выбрано то или иное неочевидное решение. Нет, правда, иногда через пару недель открываешь собственный код и не понимаешь почему было сделано именно так, а не как «правильно». После чего начинаешь делать как «правильно». А потом, потратив какое-то время натыкаешься на ограничение о котором ты тупо забыл. И вот если бы оно было в комментарии, то и не пришлось бы переделывать как «правильно». Это только один пример, разных подобных ситуаций и их вариаций куча.

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

                            Насчёт delete/undefined это только пример. К сожалению не придумал более удачного примера, который был бы понятен широкому кругу.

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

                            Например, когда я писал расширение, о котором эта статья, я ужасно много времени потратил на разные способы работы с текстом. Методом долгих и мучительных проб и ошибок я понял среди прочего, что категорически не стоит связываться с юникодом, по возможности работать с текстом побайтово. Но у меня короткая память, плюс в голове очень много вещей, поэтому я тупо могу забыть эти принципы, и снова начать работать с юникодом. Или когда я опубликую исходный код, другие ребята могут наступить на те же грабли. Вот для этого комментарии нужны.
                            +2
                            Человеку, который не знает, что такое IRQ, нечего делать на таких, с позволения сказать, кроватях. Ой. В исходниках, где идет работа с IRQ. И даже двумя этажами выше.
                              0

                              С методологической точки зрения вопрос поставленный в заголовке статьи очень интересный и своевременный. Объём информации в нашем мире сейчас увеличивается многократно с каждым днём, однако извлечение смысла из этой информации это отдельная задача. Особенно остро стоит время извлечения смысла из этой информации. Поскольку в настоящее время объём исходных кодов создаваемых по всему миру множится, то вопрос качественного документирования — это тема которая взрывает мозг каждого руководителя ответственного за создание программных продуктов, а так же различных информационных моделей и в пределе цифровых двойников.
                              Одновременно с этим я бы ещё обозначил что развитие программирования проходило в различных ограничениях, включая ограничение на объём места, который занимал код и т.д.
                              Если говорить про настоящее время, я считаю, что необходимы новые формы хранения информации, которые бы позволили удовлетворить как потребность в расширенной структурированными данными о вашем коде (примеры, doxygen и его аналоги) или интерактивные документы как у wolfram research.

                                0
                                Я очень очень рад, что я не один пришел к мысли которую вы изложили в первой половине комментария. Насчет второго, тоже согласен. Имеет смысл делать UX/UI самого программирования более интерактивным, нежели только работа со статичным текстом кода.
                                0

                                Было дело, оставлял хэштеги в комментариях, чтобы тематически сгруппировать разные блоки кода. Поменял это для какого-то временного или тестового функционала, код которого мог вызвать вопросы. В таких моменты тоже приходили мысли "почему в комментариях наравне с аннотациями до сих пор нет хэштегов? Щелкнул и нашел все упоминания". Может когда-нибудь и будут :)

                                  0
                                  Дак уже есть) Ссылка на расширение VSCode в статье)
                                    0
                                    Да, спасибо, я прочитал статью :) Однако я не пишу на VSCode, предпочитаю продукты JetBrains.
                                    Я имел ввиду то, что это не общепринято и не применяется там, где могло бы быть полезным
                                  0
                                  Странно, что ни слова в статье нет про то, что комментарии в XXI уже стали умнее чем были (ну по крайней мере в некоторых IDE), хотя бы за счёт поддержки тэгов и некоторых других техних форматирования текста в комментариях для обеспечения:
                                  1. Автогенерации документации
                                  2. Автозаполнения контекстной подсказки описанием функции (объекта...) и формата её API (причём особенно это эффективно в языках, не имеющих никакой статической типизации), причём в некоторых IDE там уже можно и гиеперссылки видеть для перехода к упомянутым типам.
                                  3. А ещё есть специальные комментарии, обслуживаемые IDE — например TODO разделы и не только они, привязка к задачам и проектам

                                  А ещё через тэги к комментариях можно реализовывать расширенния для препрцессоров текста (не комментария а когда, находящегося под декарированием такого комментария) — про это тоже ни слова в статье), а так же применяемые в средах версионирования кода

                                  Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                                  Самое читаемое