Как превратить комментарии в искусство

Зачем коду нужны комментарии? Перевод статьи Андреаса Клингера из Product Hunt, которая ответит на вопрос и даст несколько советов, которые помогут их улучшить.

Если вы работаете с кодом каждый день, то комментарии просто необходимы для продуктивности средних и больших проектов. Комментарии — это не дополнение к коду. Это основа кода. Вот несколько приемов, которые помогут писать их лучше.

Ваши комментарии должны объяснять, а не описывать

«Комментарии не нужны. Хороший код говорит сам за себя.»
Если вы так считаете, то вы не понимаете, что делают комментарии. Они никогда не объясняют, что делает код. Код сам это делает. Комментарии объясняют зачем написано то или другое, и написано именно так.

Что против Зачем
Код объясняет что-то. Комментарии объясняют зачем существует этот код или зачем это сделано таким неочевидным путем.

Плохо:

	class Newsletter
  # удаляет из новостей
  def remove(stuff)
  …
  end
end

Хорошо:

class Newsletter
  # Заметка(andreasklinger): Если мы столкнемся с XYZ, то нам будет нужно удалить пользователя,
  # чтобы избежать проблем с API  ABC и DEFG. Подробнее здесь: https://.....
  def remove(stuff)
  …
  end
end

Пишите свое имя

В Product Hunt у нас была привычка оставлять свое имя рядом с комментарием, например:

Заметка(andreasklinger): Это комментарий

Но можете переложить это на git. Люди будут перемещать код, будут корректировать ваши строки. Никому не придется пытаться искать автора, если код был перемещен или был много раз отредактирован. Особенно в небольших командах, одно лишь имя поможет понять почему что-то написано или если вам нужно его улучшить/исправить.

Будьте подробны

«Следующий разработчик разберется» - это почти миф. Обычно «следующий разработчик» просто пробегает по коду и у него есть то, что он хочет сделать, а ваш код просто стоит на пути. Представьте, что следующий человек получил ваш код, но у него нет никакого контекста, все что у него есть - ОЧЕНЬ небольшое количество времени, чтобы его изменить. Все, что вы пишите очевидно для вас, пока вы пишите код, потом это больше никогда не будет так очевидно никому, включая вас.

• Объясняйте, не думая, что люди уже знают, как работает система
• Объясняйте внешние причуды системы, которые нужно учитывать
• Объясняйте внутренние причуды системы, которые нужно учитывать
• Объясняйте, какие части кода являются «наследством»
• Объясняйте, когда код (в том числе «наследство») может быть удален (пишите «после того как Х будет сделан или ставьте дату, если это возможно)
• Объясняйте, какие хаки вы использовали и почему они работают
• Объясняйте внутренние взаимозависимости, которые не очевидны (системы, на которые опирается структура или api)
• Не бойтесь писать длинные комментарии, если необходимо
• Если возможно, никогда не используйте внутреннюю документацию. Если это не в том же файл люди не будут обновлять.
• Просите оставлять заметки, также ожидайте, что ваши коллеги будут писать комментарии в любом коде по мере надобности

Избегайте беспорядка

Явно > Неявно, НО когда явного становится слишком много, вы его избегаете.

Напишите комментарии. Когда вы это сделали, прочитайте их снова и посмотрите, что вы можете удалить или упростить.
Помните, что код объясняет сложные системы машинам, комментарии делают то же самое для людей.

"Если вы не можете объяснить это просто - значит, вы сами не понимаете этого до конца."
Альберт Эйнштейн

Другие статьи по теме

Как научиться учиться?

Как научиться программировать?