Документация по коду: сколько стоит слишком много?
Сколько документации в вашем исходном коде.NET слишком много?
Немного предыстории: я унаследовал большую кодовую базу, о которой я говорил в некоторых других вопросах, которые я разместил здесь на SO. Одной из "особенностей" этой кодовой базы является God Class, единственный статический класс с>3000 строками кода, охватывающий несколько десятков статических методов. Это все из Utilities.CalculateFYBasedOnMonth() в Utilities.GetSharePointUserInfo() в Utilities.IsUserIE6(), Это все хороший код, который не нужно переписывать, просто рефакторинг в соответствующий набор библиотек. Я планировал это.
Поскольку эти методы переходят на новый бизнес-уровень, и моя роль в этом проекте состоит в том, чтобы подготовить систему к обслуживанию другими разработчиками, я думаю о документации твердого кода. Хотя все эти методы имеют хорошие встроенные комментарии, они не все имеют хороший (или любой) код документа в виде комментариев XML. Используя комбинацию GhostDoc и Sandcastle (или Document X), я могу создать довольно симпатичную HTML-документацию и опубликовать ее в SharePoint, что позволит разработчикам лучше понять, что делает код, без навигации по самому коду.
По мере увеличения объема документации в коде становится сложнее перемещаться по коду. Я начинаю задумываться, не сделает ли XML-комментарии код труднее поддерживать, чем, скажем, проще //comment будет на каждом методе.
Эти примеры взяты из образца Документа X:
/// <summary>
/// Adds a new %Customer:CustomersLibrary.Customer% to the collection.
/// </summary>
/// <returns>A new Customer instance that represents the new customer.</returns>
/// <example>
/// The following example demonstrates adding a new customer to the customers
/// collection.
/// <code lang="CS" title="Example">
/// CustomersLibrary.Customer newCustomer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith");
/// </code>
/// <code lang="VB" title="Example">
/// Dim newCustomer As CustomersLibrary.Customer = myCustomers.Add(CustomersLibrary.Title.Mr, "John", "J", "Smith")
/// </code>
/// </example>
/// <seealso cref="Remove">Remove Method</seealso>
/// <param name="Title">The customers title.</param>
/// <param name="FirstName">The customers first name.</param>
/// <param name="MiddleInitial">The customers middle initial.</param>
/// <param name="LastName">The customers last name.</param>
public Customer Add(Title Title, string FirstName, string MiddleInitial, string LastName)
{
// create new customer instance
Customer newCust = new Customer(Title, FirstName, MiddleInitial, LastName);
// add to internal collection
mItems.Add(newCust);
// return ref to new customer instance
return newCust;
}
А также:
/// <summary>
/// Returns the number of %Customer:CustomersLibrary.Customer% instances in the collection.
/// </summary>
/// <value>
/// An Int value that specifies the number of Customer instances within the
/// collection.
/// </value>
public int Count
{
get
{
return mItems.Count;
}
}
Итак, мне было интересно от вас: документируете ли вы весь свой код с помощью комментариев XML с целью использования чего-то вроде NDoc (RIP) или Sandcastle? Если нет, как вы решаете, что получает документацию, а что нет? Что-то вроде API, очевидно, будет иметь doco, но как насчет кодовой базы, которую вы собираетесь передать другой команде для поддержки?
Что ты думаешь я должен сделать?
14 ответов
Я думаю, что хорошей частью проблемы здесь является подробный и грубый синтаксис документации XML, который нам навязал (JavaDoc тоже был не намного лучше). Вопрос о том, как его отформатировать, в значительной степени не зависит от того, насколько он уместен.
Использование формата XML для комментариев не является обязательным. Вы можете использовать DOxygen или другие инструменты, которые распознают различные форматы. Или напишите свой собственный экстрактор документов - это не так сложно, как вы думаете, сделать разумную работу и является хорошим опытом обучения.
Вопрос насколько сложнее. Я думаю, что идея самодокументируемого кода хороша, если вы копаетесь в поддержке некоторого кода. Если вы просто клиент, вам не нужно читать код, чтобы понять, как работает данная функция. Конечно, много информации подразумевается в типах данных и именах, но есть и много других. Например, передача ссылки на объект говорит вам о том, что ожидается, но не о том, как будет обрабатываться нулевая ссылка. Или в коде OP, как обрабатываются любые пробелы в начале или конце аргументов. Я считаю, что такого рода информация должна быть документирована гораздо больше, чем это обычно признается.
Мне требуется документация на естественном языке, чтобы описать назначение функции, а также любые предварительные и постусловия для функции, ее аргументы и возвращаемые значения, которые не могут быть выражены через синтаксис языка программирования.
Никто не упоминал, что ваш код не должен быть раздутым, документация XML может быть в другом файле:
/// <include file="Documentation/XML/YourClass.xml" path="//documentation/members[@name='YourClass']/*"/>
И тогда ваш метод Add не может содержать никаких дополнительных XML/ комментариев над ним, или, если вы предпочитаете просто сводку (поскольку она объединена с отдельным файлом).
Он гораздо более мощный, чем мусорный формат, который представляет собой Javadoc и производные, которые вы найдете в PHP/Javascript (хотя Javadoc проложил путь к синтаксису XML). Кроме того, доступные инструменты намного лучше, а внешний вид справочных документов по умолчанию более удобен для чтения и более прост в настройке (я могу сказать, что из написания доклетов и сравнения этого процесса с Sandcastle/DocProject/NDoc).
Здесь вы попадаете в критическое разделение между теми, кто будет поддерживать новые библиотеки, и теми, кто будет использовать новые библиотеки.
Если я пишу новое приложение и буду использовать эти стандартные библиотеки, я должен получить стабильный двоичный файл библиотек и просто импортировать их в свое приложение, а не копировать исходный код из местоположения и потенциально вызывать проблемы, если код модифицируется. В этом случае у меня не будет доступа ни к каким "самодокументируемым" функциям, кроме имени метода и параметров ввода / вывода, и даже они не будут доступны, если я использую какую-то IDE на котором не включена функция автозаполнения.
Так что в приведенном выше примере кода, я думаю, это выглядит просто отлично. В самом коде вещи не слишком многословны, а имена самодокументированы. С другой стороны, все необходимые сводные данные / параметры имеются для того, чтобы можно было создать солидную часть документации, которая позволит тем, кто использует библиотеку, иметь всю критическую информацию под рукой. К сожалению, XML довольно раздутый, но в целом я думаю, что большинство разработчиков могут легко просматривать весь сводный контент и просматривать фактический код в методе.
У Джеффа есть действительно хорошая статья о комментировании (или я должен сказать, не комментируя) здесь...
http://www.codinghorror.com/blog/archives/001150.html
Я знаю, что кажется, что я не отвечаю на вопрос, но я думаю, что это правильная точка зрения, что код должен быть как можно более самодокументированным.
Я всегда выбираю комментарии в формате XML / Javadoc, потому что мне нравится просматривать документацию API в удобном формате (обычно HTML).
Это становится проблемой для просмотра реального исходного кода, но я считаю, что это, как правило, незначительная проблема, так как Visual Studio, как правило, довольно умна в отношении свертывания комментариев XML по мере необходимости.
Все общедоступные функции должны быть четко понятны кому-то, кто знаком с вашей базой кода, но НЕ в вашем конкретном разделе без необходимости углубляться в код.
Если вам нужно написать короткую строку, чтобы объяснить, что делает функция, скорее всего, вы плохо назвали свою функцию / классы. Имя должно быть самоочевидным в этом случае
Если для объяснения требуется более одного краткого предложения, это, вероятно, хороший комментарий.
Если он занимает абзац, ваша функция, вероятно, делает слишком много, кроме вероятных неясных имен.
Обычно лучше ошибиться в комментариях, если вы уверены, что они точны. Неточные и / или недостоверные комментарии хуже, чем отсутствие комментариев
Итак, применяя эти правила:
В вашем первом примере: "// создать новый экземпляр клиента" является избыточным. Код кристально чистый. Другие комментарии идеальны. Они разъясняют, над чем работает код / каковы его результаты
В вашем втором примере комментарии - это напрасная трата усилий, которые затрудняют чтение. Все, что вам нужно сделать, это дать правильное имя функции. Не то смутное "граф". Это плохое наименование.
Недавно я провел исследование, которое показывает, что если у вас есть важные "директивы", например, Caller должен выполнить X"во многих спецификациях (например," этот метод делает X, что означает Y и Z"), существует очень высокий риск того, что Ваши читатели будут пропускать директивы. Фактически, когда они видят длинную документацию, они пропускают ее чтение полностью.
Поэтому, по крайней мере, выделите важные вещи или используйте теги (спросите меня, используете ли вы Java).
Все зависит от стандартов, которые использует ваша компания, но для моей команды мы документируем все функции, как во втором примере (что, кстати, вы можете сделать в Visual Studio 2008, нажав клавишу "/" 3 раза). в ряд в верхней части любого сабвуфера или функции!!).
Первый пример - перебор, особенно нижняя пара строк, где каждая строка комментируется. Тем не менее, я думаю, что материал в заголовке функции может быть полезен, потому что мы часто используем его здесь. И это выглядит несколько стандартно из того, что я могу сказать от многих других программистов.
Я склонен документировать все публичные методы в своем собственном коде; использование GhostDoc делает это тривиальным. И чтобы уменьшить беспорядок при редактировании исходного кода, я обычно просто сворачиваю комментарии, сначала переходя в "режим контура" (т. Е. Используйте команду Outline > Collapse to Definitions в Visual Studio).
Я никогда не пробовал Sandcastle, но я действительно ценю удобство, предоставляемое Intellisense для методов, которые я комментировал XML.
Не повторяйся.
- Первый пример должен иметь лучшее имя метода и вообще без комментариев.
- Во втором примере не должно быть комментариев.
Имя первого метода должно отражать, что выделен новый объект.
Если это поведение является стандартным во всей структуре для каждого добавления, оно должно быть документировано на более высоком уровне, а не в этом методе API doc. В противном случае измените имя.
Комментарии должны добавлять информацию, а не скрывать ее в шуме. И там должны быть комментарии, где это необходимо в XML. И где они добавляют ценность.
Я не хочу видеть: "возвращает счет" для метода с именем count.
То, что вы показали, это слишком далеко. Сделайте себе одолжение и удалите его!
Во-первых, код должен быть самодокументированным, через осмысленные имена методов и параметров. В приведенном вами примере;
public Customer Add (заголовок заголовка, строка FirstName, строка MiddleInitial, строка LastName) вполне понятен для целей происходящего, как и "Count".
Как вы указали, такие комментарии - это просто шум вокруг того, что в противном случае легко прочитать код. Большинство разработчиков скорее откроют для изучения и использования код, чем копятся в неясной автоматически сгенерированной документации API. Каждый раз!
Комментарии в шапке для генерации документации - это хорошо. Добавление комментариев в код для объяснения того, почему вы делаете то, что вы делаете, обычно тоже хорошо. Вставлять лишние комментарии, перефразируя то, что вы сделали, не очень хорошая вещь
Кстати, согласно "Чистому коду" (отличная книга, кстати), следует избегать использования разметки HTML/XML внутри комментариев, встроенных в исходный код. Даже если ваша IDE может создавать отличную документацию при наведении курсора, она считается слишком отвлекающей и нечитаемой, когда вы просто просматриваете свои источники.
Я видел стандарты кодирования, которые рекомендуют не комментировать самокомментирующий код и перегрузки методов. В то время как YMMV, это звучит как хороший способ уйти от "Поле _numberOfCars - это целое число, представляющее количество автомобилей", которое приводит к перерасходу комментариев.