Иногда очень сложно решить, когда именно вы написали достаточно комментариев, чтобы кто-то понял ваши намерения.
Думаю, нужно просто сосредоточиться на написании читаемого, легко понятного кода, чем на том, чтобы включить большое количество строк комментариев, объясняющих каждую деталь происходящего.
Каковы ваши взгляды на это?
Комментарии не существуют, чтобы объяснить, что вы делаете. Они могут объяснить, почему вы это делаете.
Аргумент основан на ложной дилемме: либо ваш код является ужасным мерзостью, и вы пишете тонны комментариев, чтобы объяснить каждое утверждение и выражение, или ваш код - прекрасная поэзия, которую может понять ваша бабушка без какой-либо документации.
В действительности вы должны стремиться к последним (ну, может быть, не вашей бабушке, а другим разработчикам), но понимаете, что бывают случаи, когда несколько комментариев будут устранять двусмысленность или сделать следующие десять строк кода более простой. Люди, которые не поддерживают никаких комментариев, являются экстремистами.
Конечно, следует избегать безвозмездных комментариев. Никакое количество комментариев не поможет плохому коду быть более понятным. Они, вероятно, просто ухудшают ситуацию. Но если вы только кодируете тривиальные системы, будут моменты, когда комментарии будут уточнять принятые дизайнерские решения.
Это может быть полезно при обнаружении ошибок. Грамотный код может выглядеть совершенно законным, будучи совершенно неправильным. Без комментариев другие (или вы полгода спустя) должны угадать о ваших намерениях: вы имели в виду это, или это был несчастный случай? Это ошибка, или это где-то в другом месте? Может быть, я должен обратиться к проектной документации... Комментарии - это встроенная документация, видимая прямо там, где вам это нужно.
Правильное решение, когда действительно существует потребность в комментариях, - это ключ.
Попробуйте сделать код самообучающимся. Одна из самых важных вещей - использование значимых имен для классов, функций, переменных и т.д.
Прокомментируйте разделы, которые не являются самообучающимися. Тривиальное комментирование (например, я ++;//Добавление 1 в i) делает код более трудным для чтения.
Кстати, чем ближе к псевдокоду вы можете работать, тем более самоочевидным может стать ваш код. Это привилегия языков высокого уровня; трудно сделать самоочевидный ассемблерный код.
Не весь код является самодокументированным.
Сейчас я пытаюсь устранить проблему с производительностью. Разработчик подумал, что он обнаружил источник узкого места; блок кода, который почему-то спал. В этом коде не было комментариев, нет контекста относительно , почему он был там. Мы удалили блок и повторно протестировали. Теперь приложение не работает под нагрузкой, где раньше не было.
Мое предположение, что кто-то ранее столкнулся с проблемой производительности и помещал этот код для смягчения проблемы. Было ли это правильным решением, это одно, но несколько комментариев о , почему этот код теперь будет спасать нас от боли и целых много времени...
Зачем вам нужны комментарии. Имя метода должно быть достаточно ясным, чтобы вам не нужны комментарии.
Пример:
// This method is used to retrieve information about contact
public getContact()
{
}
В этом случае getContact не нуждается в комментариях
Цель для кода, который не нуждается в комментариях, но не слишком сильно избивайте себя, если вы пропустите.
Я думаю, что комментирование достаточно, чтобы вы могли это понять, если бы вам пришлось пересмотреть свой код позже в жизни, должно быть достаточно.
Я думаю, что было бы потрачено много времени, если бы вы прокомментировали всех; и этот маршрут может сделать ваш код еще более трудным для понимания.
Я согласен с тем, что писать читаемый код, вероятно, является самой важной частью, но не оставляйте комментарии. Возьмите дополнительное время.
Считываемый код должен быть приоритетом номер 1. Комментарии, как писал Пол Томблин, сосредоточиться на том, почему.
Я стараюсь избегать комментариев как можно больше. Код должен быть понятным. Правильно именуйте переменные и методы. Разбивайте большие кодовые блоки в методах, имеющих хорошее имя. Напишите методы, которые делают одно, то, на что вы их назвали.
Если вам нужно написать комментарий. Сделайте это коротким. У меня часто возникает ощущение, что если вам нужно подробно рассказать о том, почему этот блок кода делает это и что у вас уже есть проблема с дизайном.
Только комментарий, когда он что-то добавляет.
Что-то вроде этого бесполезно и определенно уменьшает читаемость:
/// <summary>Handles the "event" event</summary>
/// <param name="sender">Event sender</param>
/// <param name="e">Event arguments</param>
protected void Event_Handler (object sender, EventArgs e)
{
}
В принципе, оставляя в стороне хороший, но возможно короткий комментарий в начале объявления класса/метода/функции, и, если необходимо, вступительный комментарий в начале файла, комментарий будет полезен, когда не так - закодирована обычная или нечетко прозрачная операция.
Так, например, вы должны избегать комментирования того, что очевидно (i ++; в предыдущем примере), но то, что вы знаете, менее очевидно и/или более сложное, должно заслуживать четкой, неконфузирующей, блестящей, полной строки комментария, которая естественно приходит вместе с Нобелевской премией за самый четкий код в истории;).
И не стоит недооценивать тот факт, что комментарий должен быть смешным; программисты читают гораздо радостнее, если вы можете разумно дразнить их.
Итак, поскольку общий принцип, как правило, не преуспевает в комментариях, но когда вам приходится писать одно, будьте уверены, что это самый яркий комментарий, который вы могли бы записать.
И лично я не большой поклонник самодокументирующего кода (так называемый код с одним проклятым slashstar): после нескольких месяцев вы его написали (это просто дни для моего личного масштаба), это очень вероятно, t сказать истинную причину выбора такого дизайна для представления этой части вашего интеллекта, так как могли другие?
Комментарии - это не просто зеленый материал среди строк кода; они являются частью кода, который ваш мозг лучше готов к компиляции. Квалификация как braincode (смех) Я не мог утверждать, что комментарии не являются частью программы, которую вы пишете. Это всего лишь часть, которая не направлена на процессор.
Обычно я являюсь поклонником комментариев к документации, которые четко указывают на намерение кода, который вы пишете. Spiffy инструменты, такие как NDoc и Sandcastle, обеспечивают хороший, последовательный способ записи этой документации.
Однако за последние годы я заметил несколько вещей.
Большинство комментариев к документации на самом деле не говорят мне ничего, что я действительно не могу извлечь из кода. Это предполагает, конечно, что я могу сделать головы или хвосты из исходного кода для начала.
Комментарии должны использоваться для документирования намерения, а не поведения. К сожалению, в подавляющем большинстве случаев это не так, как они используются. Такие инструменты, как NDoc и Sandcastle, распространяют неверное использование комментариев, предоставляя множество тегов, которые побуждают вас предоставлять комментарии, которые рассказывают читателю, что он должен уметь распознавать сам код.
Со временем комментарии, как правило, не синхронизируются с кодом. Это, как правило, верно, независимо от того, используем ли мы программное обеспечение для документации, которое требует упрощения документации, поскольку оно приближает документацию к описываемому им коду. Несмотря на то, что документация находится рядом с методом, свойством, событием, классом или другим типом, разработчикам все еще приходится запоминать обновление, если и когда изменяется внутреннее поведение. Следовательно, документация теряет свою ценность.
Стоит отметить, что эти проблемы в основном связаны с неправильным использованием комментариев. Если комментарии используются исключительно как средство передачи намерения, эти проблемы идут по пути додо, поскольку намерение любого данного типа или его членов вряд ли со временем изменится. (Если это так, лучший план состоит в том, чтобы написать нового участника и отказаться от старого с ссылкой на новый.)
Комментарии могут иметь огромное значение, если они используются должным образом. Но это означает знание того, для чего они лучше всего используются, и ограничение их использования в этой области. Если вы этого не сделаете, то в результате вы получите множество комментариев, которые являются неправильными, вводящими в заблуждение и источником трудоемкости (с увеличенной стоимостью), поскольку теперь вам нужно либо удалить их, либо каким-то образом исправить их.
Это стоит того, чтобы иметь стратегию для использования комментариев значимым образом, который мешает им стать временем, энергией и потоком денег.
Исследования показали, что оптимальная читаемость происходит, когда у вас есть около 1 строки комментариев для 10 строк кода. Конечно, чтобы не сказать, что вам нужно держать свой рацион в 1/10 и паниковать, если вы перейдете. Но это хороший способ дать вам представление о том, сколько вы должны комментировать.
Также помните, что комментарии - это запах кода. То есть они могут указывать на плохой код, но не обязательно так. Причина этого заключается в том, что более сложный для понимания код больше комментируется.