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