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