Что я должен включить в заголовок документации моего класса

Я ищу формат документации информативного класса для моих классов Entity, Business Logic и Data Access.

Я нашел следующие два формата отсюда

Формат 1

///-----------------------------------------------------------------
///   Namespace:      <Class Namespace>
///   Class:          <Class Name>
///   Description:    <Description>
///   Author:         <Author>                    Date: <DateTime>
///   Notes:          <Notes>
///   Revision History:
///   Name:           Date:        Description:
///-----------------------------------------------------------------

Формат 2

// ===============================
// AUTHOR     :
// CREATE DATE     :
// PURPOSE     :
// SPECIAL NOTES:
// ===============================
// Change History:
//
//==================================

Я чувствую, что следующие основные элементы

• автор
• Дата создания
• Описание
• лист регистраций изменений

так как Namespace и Class name будут там в любом случае.

Пожалуйста, дайте мне знать ваши мысли, какой формат рекомендуется и есть ли стандартный способ записи истории изменений?

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

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

Было бы утомительно искать в хранилище каждый раз, когда вы хотите узнать другую информацию? Я бы сказал нет. Как часто вы заботитесь о том, кем был первоначальный автор? Или когда файл был впервые создан? Плагины (такие как Ankh SVN для Visual Studio) часто позволяют вам щелкнуть правой кнопкой мыши в текущем файле и просмотреть журнал хранилища для файла, так что на самом деле не так уж сложно увидеть эту информацию.

Кроме того, если вы храните историю версий в комментарии, этот комментарий необходимо сохранить. Так что со временем есть шанс, что он может лгать вам. Хранилище исходного кода автоматически сохраняет эти исторические данные, поэтому не требует такого обслуживания и будет точным.

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

Прочитайте эту статью Джефф Этвуд - Кодирование без комментариев .

Я использую стандартные теги для генерации документации. Ни больше ни меньше. Посмотреть здесь

Я никогда не помещал информацию, которая не принадлежит классу. Автор, данные, редакции - это данные для хранения в системе контроля версий.

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

Большая часть этой информации может быть добавлена ​​вашим репозиторием управления версиями, оставляя вас на самом деле только с описанием, которое должно точно описывать область действия и поведение класса. Я рекомендую взглянуть на некоторые из Javadoc для Java JDK в качестве примера.

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

Если мне нужно прочитать ваше «Описание», чтобы выяснить, что делает ваш класс, то либо (а) вы плохо его назвали, либо (б) вы написали плохой класс, который делает слишком много (SRP).

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

• Описание - что делает код.
• Примечания. Все, что необходимо знать о коде, которое нелегко получить из комментариев в самом коде.
• Ссылки - Любые ссылки, от которых зависит код, которые не разъяснены при использовании includeили подобных утверждений.

Одним из элементов, который также может быть полезно включить, является раздел « Ключевые слова». Хотя вы можете выполнять поиск имен функций, классов, структур и т. Д., Могут существовать некоторые ключевые слова, которые другие имена в файле не проясняют. Или для более старого, плохо документированного кода, это может быть первым шагом в документировании кода для обслуживания.

Большинство других ответов, которые я прочитал, предполагали, что всегда доступен только один репозиторий.

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

• class documentation header (= блок комментария в начале файла) содержит только необходимую правовую информацию (например, авторские права на xyz по лицензии gpl)
• все, что должен знать разработчик, использующий класс, должно входить в class-java-doc-comments (или его эквивалент .net), чтобы современные ide-ы могли отображать эту информацию в виде всплывающей подсказки в исходном коде, использующем класс.

Вы также можете добавить номер билета для исправления ошибки или запроса на добавление функции, чтобы вы могли иметь некоторое представление о том, где, когда и почему был создан класс (если вам повезет, вы сможете получить доступ к билетам через несколько лет).

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