23 January

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

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

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

Очень боюсь критики и токсичных комментариев, но еще больше хочу узнать что вы об этом думаете?
Tags:документациякомментирование кодаvscodeинструменты разработчика
Hubs: Programming
+21
9.1k 38
Comments 26
Ads