Каковы ваши лучшие рекомендации для комментариев? Когда они должны использоваться и что они должны содержать? Или нужны комментарии?
Как вам нравятся ваши комментарии?
Ответ 1
Комментарии необходимы для ремонтопригодности. Самый важный момент для запоминания - объяснить ПОЧЕМУ, что вы делаете что-то, а не WHAT, которое вы делаете.
Ответ 2
В школе правило заключалось в том, чтобы прокомментировать все, настолько, что комментарии перевешивают код. Я думаю, что это глупо.
Я думаю, что комментарии должны использоваться для документирования кода "почему", а не "как"... сам код объясняет "как". Если есть операция, которая не совсем понятна, почему это делается, это хорошее место для комментария.
TODO и FIXME иногда идут в комментариях, но в идеале они должны идти в вашем управлении исходным кодом и инструментах отслеживания ошибок.
Единственное исключение, где я не возражаю, по-видимому, бесполезные комментарии - для генераторов документации, которые будут печатать документацию только для функций, которые комментируются - в этом случае каждый открытый класс и интерфейс API должны быть прокомментированы как минимум достаточно для того, чтобы получить документацию.
Ответ 3
В идеале ваша программа может общаться с читателем в коде, а не в комментариях. Возможность писать программное обеспечение, которое могут быстро понять другие программисты, отделяет лучших программистов от среднего по моему мнению. Как правило, если вы или ваши коллеги не можете понять раздел кода без комментариев, то это "запах кода", и рефакторинг должен быть в порядке. Тем не менее, есть некоторые архаичные библиотеки или другая интеграция, что несколько комментариев для руководства средним разработчиком не обязательно являются плохими.
Ответ 4
Как часто ответ: это зависит. Я думаю, что причина, по которой вы написали комментарий, очень важна для решения, если комментарий хороший или плохой. Существует несколько возможных причин для комментариев:
- чтобы сделать структуру более четкой (т.е. какой цикл закончился здесь)
Плохо: Это похоже на возможный запах кода. Почему код настолько сложный, что ему нужен комментарий, чтобы очистить его?
- чтобы объяснить, что делает код
Очень плохо: Это, на мой взгляд, опасно. Часто это произойдет, что вы позже измените код и забудете о комментарии. Теперь комментарий неправильный. Это очень плохо.
- для указания обходного пути/исправления
Хорошо: Иногда решение проблемы кажется ясным, но простой подход имеет проблему. Если вы исправите проблему, может быть полезно добавить комментарий, почему был выбран этот подход. В противном случае другой программист позже может подумать, что он "оптимизирует" код и повторно вводит ошибку. Подумайте о проблеме Debian OpenSSL. Debian-разработчики удалили унифицированную переменную. Обычно унифицированная переменная является проблемой, в этом случае она необходима для случайности. Кодовый комментарий помог бы прояснить это.
- для целей документирования
Хорошо: Некоторая документация может быть сгенерирована из специальных форматированных комментариев (т.е. Javadoc). Полезно документировать общедоступные API-интерфейсы, которые являются обязательными. Важно помнить, что документация содержит намерение кода, а не реализацию. Поэтому отвечает на вопрос: "Почему вам нужен метод (и как вы его используете)" или "Что делает метод?
Ответ 5
Только некоторые замечания:
Комментарии важны для всего, что не может быть легко выведено из кода (например, сложных математических алгоритмов).
Проблемы с комментариями заключаются в том, что их нужно поддерживать как код, но часто не поддерживаются вообще.
Мне не нравятся такие комментарии:
// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
лучше:
CreateAnalyzeButton();
void CreateAnalyzeButton()
{
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );
}
Теперь код рассказывает всю историю. Нет комментариев.
Ответ 6
Я думаю, это зависит от сценария.
Методам/функциям/классам требуется краткое описание того, что они делают, как они это делают, что они берут и что они возвращают, если не сразу очевидны и что обычно (в моем коде) происходит в виде javadoc- стиль комментария блок.
В блочном коде я предпочитаю оставить комментарий над блоком строк, чтобы объяснить, что он делает, или один в конце строки, если это короткий и загадочный вызов функции.
Ответ 7
Я думаю, что новое движение для удаления комментариев плохое... Причина в том, что есть много программистов, которые думают, что они пишут легко понять код, который не нуждается в комментариях. Но на самом деле это просто не так.
Какой процент кода других людей вы читаете и мгновенно понимаете. Возможно, я читаю слишком много классических asp, Perl и С++, но большинство материалов, которые я читаю, сложно сбрасывать.
Вы когда-нибудь читали код, и его полностью смущали. Как вы думаете, они думали, когда они пишут, это дерьмо, но мне все равно. Вероятно, они думали, что... это очень умно, и это будет SUPER быстро.
Ответ 8
Используйте поиск тегов, и вы обнаружите, что SO имеет кучу обсуждения комментариев кода:
Ответ 9
Посмотрите Code Complete. Он просто лучше подходит для таких тем.