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

Question

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

Однако я читаю комментарии, которые описывают, почему что-то делается и как это делается (обычно однострочные комментарии в коде); они очень полезны при попытке понять чужой код.

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

Примером может быть:

//loop though all the names from n to j - 1

Кроме этого, я не могу себе представить, почему кто-то будет тратить драгоценное время на написание комментариев, когда он может писать код.

Я прав или нет? Я что-то пропустил? О каких других хороших случаях использования комментариев я не знаю?

Answer 1

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

Answer 2

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

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

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

Answer 3

Если вы используете что-то вроде 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

Answer 4

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

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

Answer 5

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

Answer 6

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

Answer 7

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

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

Answer 8

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

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

Answer 9

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

Answer 10

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

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

... ладно, система контроля версий сказала бы мне это. Чего это мне не скажет, так это почему Lumpy прокомментировал этот, казалось бы, необходимый фрагмент кода. Так как Лумпи находится в Эльбонии, я не смогу узнать до понедельника, когда они все вернутся с праздника Snerkrumph.

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

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