Как тебе твои комментарии?

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

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

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

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

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

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

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

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

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

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

Комментирующий код

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

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

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

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

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

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

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

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

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

Хороший: Некоторая документация может быть создана из комментариев специального формата (например, Javadoc). Полезно документировать общедоступные 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 );
}

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