Хорошие варианты использования комментариев
Я всегда ненавидел комментарии, которые заполняют половину экрана звездочками только, чтобы сказать Вам, что функция возвращает строку, я никогда не читал те комментарии.
Однако я действительно читаю комментарии, которые описывают, почему что-то сделано и как это сделало (обычно однострочные комментарии в коде); натолкнутые действительно удобный при попытке понять чужой код.
Но когда дело доходит до записи комментариев, я не пишу, что, скорее использую комментарии только при записи алгоритмов в программировании конкурсов, я думал бы, как алгоритм сделает то, что это делает тогда, я записал бы каждому в комментарии, затем написал бы код, который соответствует тому комментарию.
Пример был бы:
//loop though all the names from n to j - 1
Кроме этого я не могу вообразить, почему любой потратил бы впустую комментарии записи бесценного времени, когда он мог писать код.
Я прав или неправ? Я пропускаю что-то? Что другие хорошие варианты использования комментариев я не знающий?
10 ответов
Если вы используете что-то вроде 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» должна быть сразу понятна даже начинающему программисту из одного кода. Объяснение причины, по которой вы это делаете, может улучшить читаемость.
Я использую комментарии в следующих ситуациях:
- Комментарии к высокоуровневой документации API, т.е. для чего предназначен этот класс или функция?
- Комментарий «почему».
- Краткое обобщение того, что делает гораздо более длинный блок кода. Ключевым словом здесь является сводка . Если кому-то нужны более подробные сведения, код должен быть достаточно ясным, чтобы они могли получить это из кода. Смысл здесь в том, чтобы облегчить кому-то, просматривающему код, выяснить, где находится какая-то часть логики, без необходимости углубляться в детали того, как она выполняется. В идеале эти случаи должны быть выделены в отдельные функции, но иногда это просто невозможно, потому что функция будет иметь 15 параметров и / или не будет именоваться.
- Выявление тонкостей, которые видны при чтении кода, если вы действительно обращаете внимание, но не выделяйтесь так сильно, как должны, учитывая их важность.
- Когда у меня есть веская причина, почему мне нужно делать что-то хакерским способом (производительность и т. Д.), И я не могу писать код более четко вместо использования комментария.
Неплохая идея записывать то, что, по вашему мнению , ваш код должен достигать (особенно, если код не интуитивно понятен, если вы хотите свести количество комментариев к минимуму), чтобы кто-то читал это более поздняя дата имеет более легкое время при отладке / исправлении ошибок. Хотя одна из самых неприятных вещей, с которыми можно столкнуться при чтении чужого кода, - это случаи, когда код был обновлен, но не комментарии ....
Другой тип комментария, который обычно бесполезен:
// Commented out by Lumpy Cheetosian on 1/17/2009
... ну, хорошо, система управления версиями сказала бы мне это. Чего он мне не скажет, так это ПОЧЕМУ Lumpy закомментировал этот, казалось бы, необходимый фрагмент кода. Поскольку Лампи находится в Эльбонии, я не смогу узнать до понедельника, когда все они вернутся с праздничного фестиваля Снеркрумф.
Учитывайте свою аудиторию и старайтесь не слышать шума. Если в ваших комментариях будет слишком много неуместной ерунды, разработчики просто проигнорируют их на практике.
Кстати: Javadoc (или Doxygen , или эквивалент) - это хорошая вещь (tm), ИМХО.
Я также использую комментарии, чтобы задокументировать, откуда появилось конкретное требование. Таким образом, разработчик позже может посмотреть на требование, которое привело к тому, что код стал таким, как он был, и, если новое требование конфликтует с другим требованием, решить его до того, как прервать существующий процесс. Там, где я работаю, требования часто могут исходить от разных групп людей, которые могут не знать о других требованиях, которым должна соответствовать система. Нас также часто спрашивают, почему мы делаем определенные вещи определенным образом для конкретного клиента, и это помогает узнать, какие запросы в нашей системе отслеживания привели к тому, что код изменился. Это также можно сделать при сохранении кода в исходной системе управления, но я также считаю эти заметки комментариями.
Есть плюсы и минусы для обоих подходов, которые вам нужно лично решить между своими обстоятельствами.
Pro для нескольких проектов:
- Отдельные сборки позволяют компилятору обеспечивать более строгое руководство, потенциально предотвращая проскальзывание связи. Это позволяет лучше поддерживать зависимости.
- Отдельные сборки могут загружаться по мере необходимости в другие проекты, что может облегчить повторное использование.
- Отдельные сборки могут предотвратить загрузку ненужного кода в процесс, поскольку они загружаются по запросу.
Минусы для нескольких проектов:
- Более сложное развертывание, поскольку больше файлов нуждается в развертывании (минор)
- Более медленная сборка/компиляция и даже потенциально время загрузки от загрузки нескольких сборок (минор)
Лично я думаю, что плюсы намного перевешивают минусы в большинстве случаев. Обычно я разделяю свои пространства имен на отдельные сборки, если они не связаны между собой. В вашем случае, вы работаете над 4 очень разными концепциями, так что мое чувство в том, что расщепление имеет наибольший смысл.
-121--4585708-Я всегда ненавидел комментарии, которые заполняют половину экрана звездочками просто сказать вам, что функция возвращает строку, я никогда не читал эти комментарии.
Некоторые комментарии в этом ключе, обычно не с форматированием , которые крайние, на самом деле существуют, чтобы помочь инструментам, таким как JavaDoc и Doxygen, создать документацию для вашего кода. Это, я думаю, хорошая форма комментария, потому что она имеет и гуманистический, и машиночитаемый формат для документации (чтобы машина могла перевести его в другие, более полезные форматы, такие как HTML), помещает документацию близко к коду, который она документирует (чтобы в случае изменения кода документация с большей вероятностью обновлялась для отражения этих изменений)и, как правило, дает хорошее (и немедленное) объяснение кому-то новому для большой кодовой базы, почему существует конкретная функция.
В противном случае я согласен со всем остальным, что было заявлено. Комментировать почему, и только когда это не очевидно. Кроме Doxygen комментариев, мой код, как правило, имеет очень мало комментариев.
-121--2894340-Прокомментируйте все, что вы считаете несложным, и вы не сможете понять, когда в следующий раз вы увидите свой код.
Я всегда ненавидел комментарии, которые заполняют половину экрана звездочками, просто чтобы сообщить вам, что функция возвращает строку, я никогда не читал эти комментарии.
Некоторые комментарии в этом ключе, обычно не связанные с форматированием , которое является крайним, на самом деле существуют, чтобы помочь таким инструментам, как JavaDoc и Doxygen, создать документацию для вашего кода. Я думаю, что это хорошая форма комментария, потому что он имеет как человеко-, так и машиночитаемый формат документации (чтобы машина могла переводить ее в другие, более полезные форматы, такие как HTML), помещает документацию близко к коду. что он документирует (так что, если код изменяется, документация, скорее всего, будет обновлена, чтобы отразить эти изменения), и, как правило, дает хорошее (и немедленное) объяснение тому, кто плохо знаком с большой базой кода, почему существует конкретная функция.
В остальном я согласен со всем остальным, что было сказано. Комментируйте, почему, и комментируйте только тогда, когда это не очевидно. Помимо комментариев Doxygen, в моем коде обычно очень мало комментариев.