Как вам ваши комментарии?[закрыто]

StackOverflow https://stackoverflow.com/questions/121945

  •  02-07-2019
  •  | 
  •  

Вопрос

Каковы ваши лучшие практики для комментариев?Когда их следует использовать и что они должны содержать?Или комментарии вообще нужны?

Это было полезно?

Решение

Комментарии необходимы для удобства сопровождения.Самое главное, что нужно помнить, это объяснить ПОЧЕМУ ты делаешь что-то, а не ЧТО ты делаешь.

Другие советы

В школе было правило комментировать все, настолько, что комментарии перевешивали код.Я думаю, это глупо.

Я думаю, что комментарии следует использовать для документирования того, «почему» стоит за кодом, а не «как»...сам код объясняет «как».Если есть операция, для которой не совсем понятно, почему она выполняется, это хорошее место для комментария.

TODO и FIXME иногда добавляются в комментарии, но в идеале они должны быть в ваших инструментах управления исходным кодом и отслеживания ошибок.

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

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

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

  • чтобы сделать структуру более понятной (т.какой цикл здесь закончился)

Плохой: Это похоже на возможный запах кода.Почему код настолько сложен, что для пояснения требуется комментарий?

  • объяснить, что делает код

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

  • чтобы указать обходной путь/исправление ошибки

Хороший: Иногда решение проблемы кажется очевидным, но у простого подхода есть проблема.Если вы решите проблему, возможно, будет полезно добавить комментарий, почему был выбран этот подход.В противном случае другой программист позже может подумать, что он «оптимизирует» код и повторно введет ошибку.Подумайте о проблеме Debian OpenSSL.Разработчики Debian удалили унитаризованную переменную.Обычно унитаризованная переменная представляет собой проблему, в данном случае она была необходима для случайности.Комментарий к коду помог бы это прояснить.

  • для целей документации

Хороший: Некоторая документация может быть создана из комментариев специального формата (т.Джавадок).Полезно документировать общедоступные API, это обязательно.Важно помнить, что документация содержит суть кода, а не реализацию.Так отвечает комментарий на вопрос «Зачем вам нужен метод (и как вы его используете)» или Что дает метод?

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

Какой процент кода других людей вы читаете и сразу понимаете?Возможно, я читаю слишком много классического asp, Perl и C++, но большую часть материала, который я читаю, сложно просмотреть.

Вы когда-нибудь читали чей-то код и совершенно запутались в нем.Думаете, они думали, пока писали, это чушь, но меня это не особо волнует.Наверное, они подумали: ох...это очень умно и так будет СУПЕР быстрый.

Просто несколько замечаний:

Комментарии важны для всего, что не может быть легко выведено из кода (например.сложные математические алгоритмы).

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

Не люблю такие комментарии:

// 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 );
}

Теперь код рассказывает всю историю.Нет необходимости в комментариях.

Я думаю, это зависит от сценария.

Методам/функциям/классам необходимо краткое описание того, что они делают, как они это делают, что они принимают и что возвращают, если это не сразу очевидно, и обычно (в моем коде) это происходит в форме блока комментариев в стиле javadoc. .

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

Используйте поиск по тегам, и вы обнаружите, что у SO уже есть куча обсуждений комментариев к коду:

https://stackoverflow.com/questions/tagged/comments

Комментирование кода

Посмотри на Код завершен.Это просто лучший вариант для таких тем.

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top