Документация кода: Сколько слишком много?

Между прочим, согласно "Чистому коду" (Замечательная книга, BTW), нужно избегать использования HTML/разметок XML в рамках комментариев, которые встраиваются в исходный код. Даже если Ваш IDE может создать изящную документацию, когда Вы толпитесь, считается слишком недовольным и нечитабельным, когда Вы просто просматриваете свои источники.

То, что Вы показали, СЛИШКОМ МНОГО. Сделайте Ваш сам польза и удалите ее!

Код должен прежде всего быть сам документирование через значимый метод и названия параметра. В примере Вы показали;

общедоступный Клиент Добавляет (Заголовок заголовка, представьте FirstName в виде строки, представьте MiddleInitial в виде строки, представьте LastName в виде строки), совершенно понятно к намерению того, что происходит, как 'количество'.

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

Я недавно провел исследование, которое показывает, что, если у Вас есть важные "директивы, "например, Вызывающая сторона должна сделать X" в большом количестве спецификаций (например, "этот метод делает X, что означает Y и Z"), существует очень высокий риск, что Ваши читатели пропустили бы директивы. На самом деле, когда они видят длинную документацию, они пропускают чтение ее в целом.

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

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

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

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

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

Если это требует, чтобы больше чем 1 краткое предложение объяснило, это - вероятно, хороший комментарий

Если это берет абзац, Ваша функция, вероятно, делает слишком много помимо вероятных неясных имен.

Обычно лучше допустить ошибку на стороне комментариев, ЕСЛИ ВЫ УДОСТОВЕРЯЕТЕСЬ, что ОНИ ТОЧНЫ. Неточные и/или неудобные в сопровождении комментарии не хуже, чем никакие комментарии

Так применение этих правил:

В Вашем первом примере: "//создают новый клиентский экземпляр", избыточно. Код совершенно прозрачен. Другие комментарии прекрасны. Они разъясняют то, на/как что работает код, он - resuls,

В Вашем втором примере комментарии являются потраченным впустую усилием и мешают читать. Все, что необходимо сделать, дают функции имя собственное. Не то, чтобы неопределенное "количество". Это - плохое именование.

Все это зависит от стандартов, которые использует Ваша компания, но для моей команды, мы документируем во главе каждой функции как в Вашем втором примере (который по тому, как можно сделать в Visual Studio 2008 путем удара "/" ключевые 3 раза подряд наверху любого sub или функции!!).

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

Я всегда выбираю XML / комментарии формата Javadoc, потому что я люблю способность просмотреть документацию API в разумном формате (HTML обычно).

Это действительно становится проблемой для просмотра фактического исходного кода, но я нахожу, что это обычно - незначительная проблема, так как Visual Studio обычно симпатична умный о сворачивании XML-комментариев по мере необходимости.

У Jeff есть действительно хорошая статья о комментарии (или если я говорю, не комментируя), здесь...

http://www.codinghorror.com/blog/archives/001150.html

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

Никто не упомянул, что Ваш код не должен быть чрезмерно увеличен в размере, документация XML может быть в другом файле:

/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>

И затем Ваш Добавлять метод не может содержать дополнительный XML/comments выше его, или если Вы предпочитаете просто сводку (поскольку это объединяется с отдельным файлом).

Это намного более мощно, чем мусорный формат, который является Javadoc и производными, которые Вы находите в PHP/Javascript (хотя Javadoc проложил путь к синтаксису XML). Плюс доступные инструменты намного выше, и вид по умолчанию документов справки более читаем и легче настроить (я могу сказать это от того, что записал doclets и сравнение того процесса к Sandcastle/DocProject/NDoc).

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

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

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

Я склонен документировать все открытые методы в своем собственном коде; использование GhostDoc делает это тривиальным. И для сокращения помехи, когда я редактирую свой исходный код, я обычно просто сворачиваю комментарии путем движения сначала в "режим контуров" (т.е. использую Схему Visual Studio> Коллапс к команде определений).

Я никогда не пробовал Замок из песка, но я действительно ценю комфорт, обеспеченный Intellisense для методов, которые я XML-прокомментировал.

Не повторяйте себя.

• Первый пример должен иметь лучшее имя метода и никакие комментарии вообще.
• Второй пример не должен иметь комментария.

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

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

Комментарии должны добавить информацию, не скрыть ее в шуме. И должны быть комментарии, в случае необходимости в XML. И где они увеличивают стоимость.

Я не хочу видеть: "возвращает количество" для метода, названного количеством.