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

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

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

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

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

Идеально Ваша программа может связаться с читателем в коде а не в комментариях. Способность записать программное обеспечение, которое могут быстро понять другие программисты, разделяет лучших программистов от среднего числа, по-моему. Как правило, если Вы или Ваши коллеги не можете понять раздел кода без комментариев, чем это - "запах кода", и рефакторинг должен быть в порядке. Однако там будут некоторые архаичные библиотеки или другая интеграция, что несколько комментариев для руководства среднего разработчика не обязательно плохо.

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

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

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

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

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

• для указания на Хороший workaround/a bugfix

: Иногда решение проблемы кажется ясным, но простой подход имеет проблему. При решении проблемы может быть полезно добавить комментарий, почему этот подход был выбран. Иначе другой программист позже может думать, что он 'оптимизирует' код и повторно представляет ошибку. Думайте о OpenSSL-проблеме Debian. Debian-разработчики удалили unitialized переменную. Обычно unitialized переменная является проблемой, в этом случае она была необходима для случайности. Комментарий к коду помог бы разрешить это.

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

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

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

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

Имеют, Вы когда-либо читаете чей-то код и стали абсолютно смущенными им. Вы думаете, что они думали, в то время как они пишут, это - дерьмо, но я действительно не забочусь. Они, вероятно, думали ohh..., это очень умно, и это будет СУПЕР быстро.

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

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

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

Используйте поиск тега, и Вы уже найдете ТАКЖЕ - "куча" дискуссии о комментариях к коду:

https://код Комментария stackoverflow.com/questions/tagged/comments

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

Несколько замечаний:

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

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

Мне не нравятся такие комментарии:

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

Теперь код рассказывает всю историю. Комментарии не нужны.