Все знают что комментарии в коде это “костыль”. В одном случае их используют как `git stash` курильщика. В других - для того чтобы заткнуть дыры в выразительности кода. А ещё все знают, что комментарии имеют свойство устаревать. И если с первым случаем можно научиться полльзоваться stash, во втором уже ничего не поделать, то для третьего просто нет пока ещё решения.
Обычно история комментария проста и печальна: код написали, открыли ПР. После втыка на ревью решили раскрыть какую-то неочевидность, добавив комментарий. Потом через год в этом коде что-то поправили. А в комментарии нет. И так после пары итераций мы можем получить комментарий, который противоречит коду, который он должен пояснять.
Можно обязать всех смотреть актуальность комментариев на код-ревью. Многие ограничиваются этим решением и больше к вопросу не возвращаются. Но я, например, не могу доверять себе не ревью. Потому что я человек. А значит, я ленив, ошибаюсь и люблю жать LGTM лишь бы от меня отстали. Специально для таких как я придумали статический анализ. Машина беспристрастна, не устаёт и всгеда готова покрасить твой ПР в красный цвет, только дай ей повод.
Чтобы приготовить антиутопическую реальность, где люди ублажают машины за лайки на ПР-ы, нужно придумать, как проверять комментарии на актуальность. Один из простейших способов - прикрепить к каждому комментарию sha всех строчек кода, которые находятся в одном блоке с ним. Если что-то в коде поменяется - должен будет поменяться и комментарий, в который нужно как минимум положить новый sha. Присыпать проверками на CI и подавать вместе с интеграцией в IDE по вкусу, чтобы снизить болевые ощущения у потребителей. Вы великолепны!
Не совсем про устаревание комментариев, но тоже по теме. Давненько мечтаю про обратный гитхабовскому автокомплит. Хочу чтобы он по коду мог сгенерировать тупой комментарий типа “эта функция выводит строчку Hello с параметром name”. Не то чтобы я не мог прочитать код и понять что он делает. Я и не надеюсь, что он будет понимать код лучше крепкого миддла.
У меня немного другое желание - хочу прогнать этот Reverse Github Co-pilot по
кодовой базе и построить индекс каким-нибудь поисковым движком. Чтобы я мог в
любой момент вбить в строку что-то вроде “найди мне функцию, которая считает
у нас ставку по кредиту”. И не припоминать, назвал я её calculateCreditRate,
getLoanYearly или ещё как-нибудь.