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

Question

Насколько много документации по коду в вашем исходном коде .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, очевидно, будет иметь документацию, но как насчет базы кода, которую вы собираетесь передать на обслуживание другой команде?

Что ты думаешь я должен сделать?

Answer 1

Я думаю, что большая часть проблемы здесь заключается в многословном и грубом синтаксисе XML-документации, который нам навязала MS (JavaDoc тоже был не намного лучше).Вопрос о том, как его форматировать, во многом не зависит от того, насколько это уместно.

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

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

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

Answer 2

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

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

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

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

Answer 3

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

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

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

Answer 4

У Джеффа есть действительно хорошая статья о комментировании (или, лучше сказать, не комментировании) здесь...

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

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

Answer 5

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

Я никогда не пробовал Sandcastle, но я очень ценю удобство, предоставляемое Intellisense для методов, которые я прокомментировал в XML.

Answer 6

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

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

Answer 7

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

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

Имя первого метода должно отражать выделение нового объекта.

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

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

Я не хочу видеть:«возвращает счетчик» для метода с именем count.

Answer 8

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

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

Если для объяснения требуется более одного короткого предложения, это, вероятно, хороший комментарий.

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

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

Итак, применяя эти правила:

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

В вашем втором примере комментарии — это напрасная трата усилий, и их становится трудно читать.Все, что вам нужно сделать, это дать функции правильное имя.Не такое уж расплывчатое «подсчет».Это плохое название.

Answer 9

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

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

Answer 10

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

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

Answer 11

Я видел стандарты кодирования, которые не рекомендуют комментировать самокомментирующий код и перегрузки методов.Несмотря на то, что YMMV, это звучит как хороший способ уйти от комментариев типа «Поле _numberOfCars — это целое число, представляющее количество автомобилей», которые приводят к излишним убийствам.

Answer 12

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

Answer 13

То, что вы показали, СЛИШКОМ МНОГО.Сделайте себе одолжение и удалите его!

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

Публичное добавление клиента (заголовок заголовка, строка FirstName, строка MiddleInitial, строка LastName) совершенно понятно с точки зрения происходящего, как и «Count».

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

Answer 14

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