Комментарии 26
Так почему же в 2020 году программисты себе не сделают такого инструмента?
Если бы я был настолько же мотивирован как и Вы я бы сел и написал нужный код, но судя по тому что вы этого не сделали, Вам оно не особо то и нужно .
Я сейчас серьезно.
Когда мне понадобился переход к определению функции в редакторе mcedit я просто сел и написал его.
Всю статью Вы рассказывали о том, что всё плохо и в мире сплошная несправедливость и эта фраза была для меня последней каплей, я написал коммент и закрыл статью. Ещё раз прошу за это прощения. Это было неправильно. Лишь замечу что если бы статья в начале бы имела намек на то, что Вы написали некий инструмент и что Вас к этому сподвигло читать было бы проще.
Ведь контента так много а времени так мало что вольно или невольно приходится думать с меня хватит, или а вау круто что уже конец!?
Зачем кому-нибудь могло бы потребоваться прыгать в код из документации по клику мышкой, мне невдомек, но про doctest в 2020 году лучше знать, чем нет.
Меня лично всегда удивляло, что 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;
}При этом по ховеру всплывает красивая подсказка. Почему нельзя по-умолчанию все эти теги рендерить красиво и при обычном просмотре функции? А по клику на комментарий переходить в режим редактирования.
Править сырцы на продакшн сервере на марсоходе с пингом 15 минут? Мсье знает толк.
В конце концов, ничего не мешает базировать код на html или xml, которые при большом желании таки можно править хоть и ed-ом.
Ну а потом, предложенный в статье способ нотации может приносить пользу в абсолютно любом текстовом редакторе, просто в VSCode будут дополнительные удобства. Например, если обозначать определение какого-то термина как предложено (например "@IRQ"), то его можно быстро найти из любого места проекта простым поиском, хоть grep-ом. Если же не обозначать так определение, то набрав в поиске «IRQ», гарантированно получим десятки, сотни результатов поиска.
Я вообще уже не представляю современную разработку сложных проектов без качественных инструментов IDE.
А я вот ровно наоборот — чем больше опыта, тем меньше IDE. Я последовательно поотключал автодополнение, подсказки из документации, детектор ошибок… Из всего зоопарка пока выжила только подсветка синтаксиса. И это такое наслаждение, прямо сродни просветлению: ничего не скачет, не прыгает, не возникает, не пропадает — набираешь код и ничто не отвлекает. Продуктивность выросла если не в разы, то уж вдвое — точно.
Совсем обленились миллениалы!
Насчет извращений с гиперссылками и прочим мета-тегам для комментариев, имхо затея не сильно жизнеспособная по ряду очевидных причин, впрочем сами наверное поймете через полгода использования (по своему опыту). Ну самое очевидное, если видите какую-то простую идею, которая на вид крайне полезна, но никто из миллиона хомячков ей не пользуется, скорее всего идея не очень, ну или вы очень уникальный и вам как раз зайдет.
А что если бы вы нажали на слово IRQ и чудесным образом, ваш IDE перенёс бы вас к месту определения этой аббревиатуры?
Мне сразу вспомнились see и link из javadoc, VS code сейчас проверять не буду, но идея замечательно по ним навигирует. А конструкции типа
/**
* @see <a href="URL#value">label</a>"
позволяют ссылать и на внешние адреса.
Для linux kernel, все перечисленное отлично работает в vim+ctags. Для C++ правда уже не так хорошо, так как не понимает контекст.
Это было 40 листов ассемблерных команд где было прокомментирована абсолютно ВСЕ строки содержащие инструкции. Ни до, ни после я такого не видел ни когда.
Друг помни если твой комментарий сложнее чем код, который он объясняет, то это плохой комментарий.
Для примера с ценой, максимум что я бы написал:
const price = 150 // копеекКомментарий в стиле delete медленнее чем undefined — убрал бы совсем. Причина проста, эта информация, в грядущем, может не быть актуальной. Пример, только сегодня выяснял почему иногда в jQ сначала пишут .hasClass потом .removeClass, оказалось раньше из-за переприсваивания строки классов: className = className.replace(" " + classNames[c] + " ", " "); браузер пытался перестроить элемент даже если список классов не менялся (возможно нет, браузеры тоже умные бывают), сейчас перед присваиванием проверяется что список не равен предыдущему, и хак на скорость — неактуален.
Ваши хаки на проект собирайте отдельно, и не стоит слепо их таскать за собой)
В примере выше про копейки, комментарий нужен не для того, чтобы обозначить тип денежных переменных (рубли или копейки), а чтобы пояснить почему такой тип был выбран.
Насчёт delete/undefined это только пример. К сожалению не придумал более удачного примера, который был бы понятен широкому кругу.
Насчёт нелюбви к комментариям — всё верно. По возможности следует писать программу так, чтобы не пришлось ее комментировать. Но не всегда это возможно.
Например, когда я писал расширение, о котором эта статья, я ужасно много времени потратил на разные способы работы с текстом. Методом долгих и мучительных проб и ошибок я понял среди прочего, что категорически не стоит связываться с юникодом, по возможности работать с текстом побайтово. Но у меня короткая память, плюс в голове очень много вещей, поэтому я тупо могу забыть эти принципы, и снова начать работать с юникодом. Или когда я опубликую исходный код, другие ребята могут наступить на те же грабли. Вот для этого комментарии нужны.
С методологической точки зрения вопрос поставленный в заголовке статьи очень интересный и своевременный. Объём информации в нашем мире сейчас увеличивается многократно с каждым днём, однако извлечение смысла из этой информации это отдельная задача. Особенно остро стоит время извлечения смысла из этой информации. Поскольку в настоящее время объём исходных кодов создаваемых по всему миру множится, то вопрос качественного документирования — это тема которая взрывает мозг каждого руководителя ответственного за создание программных продуктов, а так же различных информационных моделей и в пределе цифровых двойников.
Одновременно с этим я бы ещё обозначил что развитие программирования проходило в различных ограничениях, включая ограничение на объём места, который занимал код и т.д.
Если говорить про настоящее время, я считаю, что необходимы новые формы хранения информации, которые бы позволили удовлетворить как потребность в расширенной структурированными данными о вашем коде (примеры, doxygen и его аналоги) или интерактивные документы как у wolfram research.
Было дело, оставлял хэштеги в комментариях, чтобы тематически сгруппировать разные блоки кода. Поменял это для какого-то временного или тестового функционала, код которого мог вызвать вопросы. В таких моменты тоже приходили мысли "почему в комментариях наравне с аннотациями до сих пор нет хэштегов? Щелкнул и нашел все упоминания". Может когда-нибудь и будут :)
1. Автогенерации документации
2. Автозаполнения контекстной подсказки описанием функции (объекта...) и формата её API (причём особенно это эффективно в языках, не имеющих никакой статической типизации), причём в некоторых IDE там уже можно и гиеперссылки видеть для перехода к упомянутым типам.
3. А ещё есть специальные комментарии, обслуживаемые IDE — например TODO разделы и не только они, привязка к задачам и проектам
А ещё через тэги к комментариях можно реализовывать расширенния для препрцессоров текста (не комментария а когда, находящегося под декарированием такого комментария) — про это тоже ни слова в статье), а так же применяемые в средах версионирования кода
Как развивались комментарии к коду с 1940-х до 2020 года