Как не стоит комментировать код
Доброго времени суток! Попробуем истории из личной практики?)
Довелось мне на одном из проектов поработать с человеком, который писал комментарии к каждой строчке кода. Буквально к каждой, никаких преувеличений. Выглядело это примерно так:
# Увеличиваем счетчик на 1
i = i + 1;
# Проверяем, не больше ли 10
if (i > 10) {
# Если больше, сбрасываем
i = 0;
}
Сначала это было действительно забавно. Спустя время мы пытались объяснить, что код должен быть "самодокументируемым" (поясню для тех, кто с термином не знаком. Это некий стиль написания кода, при котором он пишется настолько ясно, чисто и понятно, что не требует внешних комментариев для понимания его логики работы).
Через примерно год его код превратился в простыню, где читать комментарии было дольше, чем разбираться в логике. А когда он уволился и нужно было править его модуль, мы осознали весь звиздец ситуации: комментарии были на русском, переменные на английском, а логика - на каком-то своём, крайне непонятном.
При этом, половина комментариев уже давно не соответствовала реальности, потому что код меняли, а комментарии не трогали. Зачем, верно?)
На самом деле, даже рад случившемуся, много полезного усвоил. После той ситуации и отношение к коду/комментариям поменялось. Стараюсь писать максимально понятно.
🌐 @helcode
Creator has disabled comments for this post.