Как сделать программу Комментарии Более полезной?

Question

Хай ребята,

Я видел людей, включая комментарии в своей программе ..

• Является ли это улучшить между программистом связи и читаемость кода, явно указав программистами намерения и предположения?

• Должны ли комментарии быть в технических терминах, а не в естественных условиях?

• Как использовать комментарии как можно эффективнее?

• Действительно ли это хорошая практика добавления комментариев к программе?

Answer 1

Комментарии должны использоваться только для объяснения , почему код такой, какой он есть. Он никогда не должен объяснять , что код делает. Что делает код, описывается кодом.

При этом некоторые языки имеют инструменты, которые ищут специальные символы в комментариях для создания документации. Java - один из таких языков. Но это не столько комментарии кода, сколько документация, которая использует тот же синтаксис, что и комментарии к языку.

Answer 2

Комментарии могут быть использованы для автоматической документации, связи между другими разработчиками, памяти, списков задач или основных пояснений функциональности. Обратите внимание, что комментарии должны быть дополнительными - если ваш код нуждается в комментариях, вам необходимо пересмотреть свой код.

Чтобы быть максимально эффективными, создайте шаблон для ваших комментариев, чтобы существовать. Опять же, это поможет не только прочитать и понять ваш код, но может помочь анализатору создать документацию для вас из ваших комментариев, если они соответствуют формату кода.

Answer 3

Я стараюсь прокомментировать каждую функцию, описывающую на высоком уровне, но точный способ, что делает функция. Точность должна быть такой, что нет необходимости читать тело функции, чтобы понять, что делает эта функция, или повторно реализовать ее, и работать с любым кодом, который ее вызывает.

Помимо этого, я стараюсь, чтобы функции были достаточно малыми, что выше в основном вся необходимая документация.

Время от времени может быть что-то неясное или нечетное в том, что делается в коде - я документирую это. Все, что не является очевидным или интуитивно правильным, или что вы потратили некоторое время на размышления, должно быть документировано.

Представьте, что у вас есть проблема с памятью и вы забудете написать эту программу через месяц. Тогда представьте, что вы должны вернуться и исправить. Что бы вы хотели прокомментировать и как эти комментарии могли быть наиболее полезными для вас?

Answer 4

Сначала попробуйте написать код, чтобы люди могли следить без комментариев.

Answer 5

Лучше сделать программу самоописательной, тогда комментариев не требуется.

Answer 6

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

Для меня комментарии объясняют, о чем я думал в то время. Таким образом, через шесть месяцев, когда я не помню, что писал, я могу использовать комментарии для понимания.

Некоторые классические использования комментариев:

• Объясняя, почему код не было сделано в наиболее очевидным образом - Такие, как взаимодействие с системами, использующими странные или старые способы говорить.
• Объясняя, какой код может называть этот код - например, в большой и сложной системе. Вы можете добавить примеры, показывающие код, который может потребоваться для вызова этого.
• Документирование исключений из текущей практики кодирования - например, устаревший код, который не был реорганизован для использования существующих систем.

Как правило, если вы когда-либо делаете что-то неочевидное, прокомментируйте это.

Альтернативный способ комментирования - начать с написания тела функции в виде комментариев. Затем разбейте комментарии и поместите код под ним. Когда он наконец работает, очистите и исправьте комментарии.

Ciao!