А никак они не развивались. С самых первых языков программирования и по сей день комментарии коду — это всего лишь статичный текст (за некоторыми исключениями, о которых я расскажу).
Ну а что там еще можно улучшить или придумать — спросите вы. Давайте поразмышляем на эту тему — можно ли как-то улучшить наш опыт взаимодействия с таким важным но так часто игнорируемым аспектом программирования как документация в коде, или по-простому комментарии.
Для начала, пару абзацев посвятим теме заголовка данной статьи. Да потому что толком-то и нету этой истории развития, так что можете назвать заголовок провокационным. Небольшой дисклеймер: сфера моих знаний ограничивается по убыванию в опыте (большой: TS, JS, Rust, средний: PHP, C++, маленький: Go, Java).
Итак, всё что у нас есть это: заброшенный и глючный JSDoc, окончательно почивший в эру TypeScript, кстати для которого есть не менее глючный и заброшенный TSDoc. Для PHP существует PHPDoc, который был слабо полезным когда я кодил на этом языке. Каюсь, в C++ у меня самый маленький опыт, поэтому не слышал ни о чём подобном, а найденный в гугле CppDoc ничего кроме грустной усмешки не вызывает. Наиболее развитый в этом плане у нас, как всегда Rust. В нём есть отличная система RustDoc, но к сожалению не всегда эргономичная и всё еще слабо поддерживаемая IDE.
Таким образом, в целом картина довольно печальная, и инфраструктура комментариев вокруг кода не изменилась с самого начала истории программирования. Комментарии выглядят так же как и 90 лет назад в условном Планкалкюле, как в ассемблерном коде компьютера лунного модуля Аполло-11.
(фото с сайта 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), а второе как менее значимое будет также решено, но чуть позже.
Не хочу утомлять вас далее кучей текста, поэтому просто вставлю гифку с еще парой примеров работы:
Очень боюсь критики и токсичных комментариев, но еще больше хочу узнать что вы об этом думаете?
Автор: anurbol
