Добавление описаний классов в код?

Я завершаю проект, над которым я работал некоторое время, и просто делаю последние штрихи.

Одна вещь, которую я хотел бы сделать, это добавить описания классов вверху каждого файла класса (чтобы помочь мне и другим программистам понять, что происходит). Моя мысль состоит в том, чтобы просто использовать кучу '/', чтобы привязать секцию к тому, чтобы я написал несколько заметок, но, может быть, есть лучший способ? Есть ли встроенный способ сделать это в Visual Studio?

/////////////////////////////////////////////////////
//                                                 //
// KillZombies.cs                                  //
//                                                 //
// Description: This class contains blah blah blah //
//                                                 //  
/////////////////////////////////////////////////////

Ответы

Ответ 1

Да, вы должны использовать нормальную документацию XML:

/// <summary>
/// Describe your class quickly here.
/// </summary>
/// <remarks>
/// Add more details here.
/// </remarks>

Таким образом, он появится в Intellisense, и если вы создадите свою документацию с помощью Sandcastle/ndoc/Doxygen и т.д., она будет выглядеть соответствующим образом.

Если вы наберете "///" в строке над вашим классом, вы должны увидеть соответствующий шаблон для начала работы. Для получения дополнительной информации см. Ссылку MSDN выше.

Ответ 2

Используйте Комментарии к документации по XML:

/// <summary>
///  This class performs an important function.
/// </summary>

При вводе трех сокращений Visual Studio поможет вам с остальными.

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

Ответ 3

Комментарии к документации XML, описанные в ответах выше, - это путь для документации классов и методов.

Если вам требуется дополнительная информация в каждом файле для текста без документации, например дата создания, кредиты, сообщения об авторских правах и т.д., вы можете добавить его в виде фрагмента или добавить его в соответствующий шаблон Visual Studio. VS имеет специальные переменные для шаблонов, таких как $username $и $time $, которые могут использоваться для автоматической вставки этих значений при каждом добавлении нового элемента на основе вашего шаблона.