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

Ответ 1

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

Блоки документации часто преувеличены, особенно строго типизированные языки. Намного больше смысла быть многословным с чем-то вроде Python или PHP, чем с С++ или Java. Тем не менее, все же приятно делать для методов и членов, которые не являются самоочевидными (например, не названное обновление).

Мне удалось много часов думать, просто комментируя, что я хочу сказать себе, если я впервые прочитал свой код. Более нарратива и меньше наблюдений. Комментарии должны не только помочь другим, но и вам самим... особенно если вы не коснулись его через пять лет. У меня есть десятилетний 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

Ответ 2

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

Ответ 3

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

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

Высказывание "цикла через все имена от n до j-1" должно быть сразу понятным даже начинающему программисту из кода. Предоставление причины, по которой вы это делаете, может помочь с удобочитаемостью.

Ответ 4

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

• Комментарии к документации по API высокого уровня, то есть для этого класса или функции?
• Комментирование "почему".
• Краткое, высокоуровневое резюме того, что делает гораздо более длинный блок кода. Ключевое слово здесь - резюме. Если кто-то хочет более подробно, код должен быть достаточно ясным, чтобы он мог получить его из кода. Дело здесь в том, чтобы сделать так, чтобы кто-то просматривал код, чтобы выяснить, где некоторая часть логики не должна пробираться сквозь детали того, как она выполняется. В идеале эти случаи должны быть заменены на отдельные функции вместо этого, но иногда это просто не работает, потому что функция будет иметь 15 параметров и/или не будет называться.
• Указание тонкостей, которые видны при чтении кода, если вы действительно обращаете внимание, но не выделяетесь так сильно, как должны придавать им значение.
• Когда у меня есть веская причина, почему мне нужно что-то делать хакерским способом (производительность и т.д.), и я не могу написать код более четко, а не использовать комментарий.

Ответ 5

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

Ответ 6

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

Ответ 7

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

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

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

Ответ 8

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

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

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

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

BTW: Javadoc (или Doxygen, или equiv.) - это хорошая вещь (tm), IMHO.

Ответ 9

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

Ответ 10

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

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

Ответ 11

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

// 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?".