Итак, я использую комментарии XML в своем коде, чтобы объяснить объяснения Public Methods и Public Members, еще один разработчик упомянул, что не все мои методы имеют комментарии XML. Я использую правило, если оно является общедоступным или защищенным, добавляет комментарий XML, если оно закрыто, не делайте этого.
Это звучит логично или есть какая-то причина, по которой вам следует XML-комментарий для частного метода?
В комментариях нет сильных правил, но я считаю, что полезно комментировать общедоступные/внутренние/защищенные методы.
Иногда я комментирую частные методы, когда они не очень понятны. В идеале код должен быть самодокументирован. Например, если у вас есть метод типа
Item GetItemByTitle(string title)
тогда не требуется писать комментарии, потому что это достаточно ясно. Но если метод может быть неясным для других разработчиков, пожалуйста, разместите свои комментарии или переименуйте/реорганизовать событие метода, если оно закрыто. Лично я предпочитаю читать код, а не комментарии:) Если у вас слишком много комментариев, код становится трудно читать. Мое правило состоит в том, чтобы использовать комментарии только тогда, когда это необходимо.
Если в вашем проекте есть возможность документировать все методы, включая частные методы, следуйте этому правилу.
Имеет смысл также комментировать частные и защищенные члены - возможные причины включают:
Я действительно не вижу веских причин, по которым вы бы ограничили комментарии XML публичными членами.
Я соглашаюсь с руководящей философией, что метод должен быть достаточно простым, чтобы его подпись точно описывает, что он делает. При этом это не всегда возможно (особенно при работе с устаревшим кодом), поэтому возникают ситуации, когда комментарий заголовка полезен. Например:
Я не думаю, что на самом деле есть какие-то жесткие и быстрые ответы здесь, если он прав, чтобы комментировать его, а затем прокомментировать его
Я всегда воспринимаю это как хорошую практику, чтобы прокомментировать все мои методы как эквивалент необходимости объяснять их кому-то, поскольку я хотел бы, чтобы они объяснили мне, если бы я не знала, что происходит, и почему.
Мы развиваемся в небольшой команде, и это действительно помогает в развитии команды. Более того, я регулярно использую свои СОБСТВЕННЫЕ комментарии, чтобы выяснить, какой черт мой процесс был 3 месяца назад, когда я смотрю на кусок кода.
Абсолютно стоит потратить некоторое время на добавление комментариев к вершине ваших методов/процедур, которые делают некоторые интересные вещи.
Вопрос немного неясен в отношении того, спрашиваете ли вы:
Чтобы ответить на первый вопрос, нужно прокомментировать любой код - это немного запаха кода. Когда вы сталкиваетесь с ситуацией, когда вы сталкиваетесь с кодом, который трудно прочесть, объясняя вам, ваша первая попытка решить это должна заключаться в изменении (обычно путем переименования вещей), чтобы код был более читабельным. Использование комментариев для объяснения нечеткого имени метода должно быть последним средством.
Есть некоторые исключения. Публичные методы DLL, совместно используемые вне решения, должны всегда комментировать.
Я рекомендую прочитать книгу Роберта К. (Дядя Боб) Мартина "Чистый код" для более подробной информации об этом.
В общем, да используйте комментарии XML для методов, а не комментарии С#. Комментарии XML появляются в intellisense. Кроме того, комментарии XML привязаны к методу, и если вы используете инструменты рефакторинга для перемещения методов, комментарии XML будут приведены вместе с этим методом, тогда как комментарии С# можно легко отделить от метода.
Одной из причин не использовать комментарии XML является то, что вы будете публично распространять свою DLL и файл комментариев XML. XML файл будет содержать комментарии для всех ваших внутренних и частных методов. Поэтому просто убедитесь, что вы в порядке со своими клиентами, потенциально читающими какие-либо из этих комментариев для частных методов.