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

Question

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

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

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

Answer 1

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

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

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

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

Answer 2

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

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

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

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

Answer 3

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

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