Хорошие варианты использования комментариев

Если вы используете что-то вроде Doxygen, вы можете полностью задокументировать свои возвращаемые типы, аргументы и т. Д. И сгенерировать приятный "Руководство по исходному коду". Я часто делаю это для клиентов, чтобы команда, наследующая мой код, не потерялась полностью (или не была вынуждена проверять каждый заголовок).

Блоки документации часто преувеличиваются, особенно это касается строго типизированных языков. Гораздо больше смысла говорить о подробностях вроде Python или PHP, чем о C ++ или Java. Тем не менее, это все еще хорошо делать для методов и членов, которые не говорят сами за себя (например, без имени update).

Я сэкономил много часов на размышления, просто комментируя то, что я хотел бы сказать себе, если бы впервые читал свой код. Больше повествования и меньше наблюдений. Комментарии должны помогать не только другим, но и себе ... особенно, если вы не прикасались к ним пять лет. У меня есть Perl десятилетней давности, который я написал, и я до сих пор не знаю, что он делает.

Что-то очень грязное, что я сделал в PHP и Python, - это использование отражения для извлечения блоков комментариев и меток элементов в пользовательском интерфейсе. Это вариант использования, хотя и неприятный.

Если вы используете трекер ошибок, я также оставлю идентификатор ошибки рядом с моими изменениями, чтобы у меня была обратная ссылка на трекер. Это дополнение к краткому описанию изменения (встроенные журналы изменений).

Я также нарушаю правило «только комментируйте, почему не что», когда делаю то, что мои коллеги редко видят ... или когда важна тонкость. Например:

for (int i = 50; i--; ) cout << i; // looping from 49..0 in reverse
for (int i = 50; --i; ) cout << i; // looping from 49..1 in reverse

Комментарии должны выражать почему вы делаете что-то, а не то, что делаете.

Это старая пословица, но хороший показатель для использования:

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

Сказание «перебрать все имена от n до j-1» должно быть сразу понятно даже начинающему программисту, исходя только из кода. Объяснение причины, по которой вы это делаете, может улучшить читаемость.

Я использую комментарии в следующих ситуациях:

1. Комментарии к высокоуровневой документации по API, т.е. для чего нужен этот класс или функция?
2. Комментируя «почему».
3. Краткое высокоуровневое резюме того, что делает гораздо более длинный блок кода. Ключевое слово здесь - резюме. Если кому-то нужны более подробные сведения, код должен быть достаточно ясным, чтобы они могли получить это из кода. Смысл здесь в том, чтобы облегчить кому-то, просматривающему код, выяснить, где находится какая-то часть логики, без необходимости углубляться в детали того, как она выполняется. В идеале эти случаи должны быть выделены в отдельные функции, но иногда это просто невозможно, потому что функция будет иметь 15 параметров и / или не будет именоваться.
4. Выявление тонкостей, которые видны при чтении кода, если вы действительно обращаете внимание, но не выделяйтесь так сильно, как должны, учитывая их важность.
5. Когда у меня есть веская причина, почему мне нужно делать что-то хакерским способом (производительность и т. Д.) И я не могу писать код более четко вместо использования комментария.

Комментируйте все, что, по вашему мнению, непросто, и вы не сможете понять, когда вы в следующий раз увидите свой код.

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

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

Некоторые комментарии в этом ключе, обычно не с таким экстремальным форматированием, на самом деле существуют, чтобы помочь таким инструментам, как JavaDoc и Doxygen, создать документацию для вашего кода. Я думаю, что это хорошая форма комментария, потому что он имеет как человеко-, так и машиночитаемый формат документации (чтобы машина могла переводить ее в другие, более полезные форматы, такие как HTML), помещает документацию близко к коду что он документирует (так что, если код изменяется, документация, скорее всего, будет обновлена, чтобы отразить эти изменения), и, как правило, дает хорошее (и немедленное) объяснение тому, кто плохо знаком с большой базой кода, почему существует конкретная функция.

В остальном я согласен со всем остальным, что было сказано. Комментируйте, почему, и комментируйте только тогда, когда это не очевидно. Помимо комментариев Doxygen, в моем коде обычно очень мало комментариев.

Другой тип комментария, который обычно бесполезен:

// Commented out by Lumpy Cheetosian on 1/17/2009

... ну, хорошо, система контроля версий сказала бы мне это. Чего он мне не скажет, так это ПОЧЕМУ Lumpy закомментировал этот, казалось бы, необходимый фрагмент кода. Поскольку Лампи находится в Эльбонии, я не смогу узнать до понедельника, когда все они вернутся с праздничного фестиваля Снеркрумф.

Учитывайте свою аудиторию и снижайте уровень шума. Если в ваших комментариях будет слишком много неуместной ерунды, разработчики просто проигнорируют их на практике.

Кстати: Javadoc (или Doxygen, или эквивалент) - это хорошая вещь (тм), ИМХО.

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

Напоминает мне о

Настоящие программисты не пишут документацию

Я написал этот комментарий некоторое время назад, и он сэкономил мне часы с тех пор:

// NOTE: the close-bracket above is NOT the class Items.
// There are multiple classes in this file.
// I've already wasted lots of time wondering,
// "why does this new method I added at the end of the class not exist?".