Привет, ребята,
Я видел, как люди включали комментарии в свою программу.
Улучшить взаимодействие между программистами и удобочитаемость кода за счет явного указания намерений и предположений программистов?
Должны ли комментарии быть в технических терминах, а не в терминах естественного языка?
Как использовать комментарии максимально эффективно?
Это действительно хорошая практика добавления комментариев к программе?
Комментарии следует использовать только для объяснения почему код такой, какой он есть. Он никогда не должен объяснять, что делает код. То, что делает код, описывается кодом.
При этом в некоторых языках есть инструменты, которые ищут специальные символы в комментариях для создания документации. Java — один из таких языков. Но это не столько комментарии к коду, сколько документация, использующая тот же синтаксис, что и языковые комментарии.
Комментарии можно использовать для автоматического документирования, общения с другими разработчиками, памяти, списков задач или базовых объяснений функциональности. Обратите внимание, что комментарии должны быть дополнительными — если ваш код нуждается в комментариях, вам нужно пересмотреть свой код.
Чтобы быть максимально эффективным, разработайте шаблон, в котором будут существовать ваши комментарии. Опять же, это не только поможет вам читать и понимать ваш код, но и может помочь синтаксическому анализатору создать для вас документацию из ваших комментариев, если они находятся в единый формат во всем коде.
Написание понятного кода — это всегда первый шаг к тому, чтобы сделать ваш код простым для понимания. Затем вы можете объяснить непонятные части, просмотрев код в комментариях.
Для меня комментарии объясняют, о чем я думал в то время. Таким образом, через шесть месяцев, когда я не буду помнить, что я писал, я смогу использовать комментарии, чтобы понять.
Некоторые классические варианты использования комментариев:
Как правило, если вы когда-нибудь обнаружите, что делаете что-то неочевидное, прокомментируйте это.
Альтернативный способ комментирования — начать с написания тела функции в виде комментариев. Затем разбейте комментарии и поместите код под ними. Когда это, наконец, заработает, очистите и исправьте комментарии.
Чао!
Я стараюсь комментировать каждую функцию, описывая на высоком уровне, но точно, что делает функция. Точность должна быть такой, чтобы не было необходимости читать тело функции, чтобы понять, что она делает, или повторно реализовать ее, чтобы она отлично работала с любым кодом, который ее вызывает.
Кроме этого, я стараюсь, чтобы функции были достаточно маленькими, чтобы все вышеперечисленное представляло собой практически всю необходимую документацию.
Время от времени в коде может быть что-то неясное или странное — я это документирую. Все, что не является очевидным или интуитивно правильным, или над чем вы потратили некоторое время на размышления, должно быть задокументировано.
Просто представьте, что у вас проблемы с памятью, и вы забудете написать эту программу через месяц. Затем представьте, что вам нужно вернуться и исправить это. Что бы вы хотели прокомментировать и как сделать эти комментарии наиболее полезными для вас?
лучше сделать программу самоописывающей, тогда комментариев много не надо.
Сначала попробуйте написать код, чтобы люди могли следить за ним без комментариев.
