Куда поместить документирующие комментарии?

Question

Очень короткий вопрос: при оформлении кода delphi (с целью включения внешнего инструмента для создания документации HTML (Doc-o-matic в конкретном примере)), вы помещаете документальные комментарии в интерфейс или в реализацию раздел?

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

С другой стороны, у Doc-o-matic возникают проблемы время от времени, когда я добавляю комментарии к документу в части реализации.

Что вы предпочитаете?

Answer 1

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

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

SrbShell suggests размещение документации в интерфейсе, и, безусловно, удобно иметь все рядом, , когда не используется генератор документации. Но это становится намного менее важным, когда у вас есть программа, которая собирает документацию со всего кода и объединяет все вместе. В этом случае ожидается, что вы будете , используя сгенерированную документацию. Когда вы подготовили документацию, обратитесь к этому, вместо того, чтобы найти документацию в коде. IDE может даже быть настроен для отображения описаний во всплывающем окне, поэтому вам не придется смотреть на него в отдельном месте большую часть времени.

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

Answer 2

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

Answer 3

Я добавил комментарии «Сводка» в интерфейс, а также полное описание, параметры и т. Д. В часть реализации. Таким образом, вы можете посмотреть интерфейс Unit/Class, и вы сразу увидите, что он делает - без загрязнения ...

Answer 4

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

BTW, я использую Doc-O-Matic, и он отлично работает с комментариями в разделе реализации. С какими проблемами вы сталкиваетесь при написании комментариев в разделе реализации?

Answer 5

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

Обычно мой метод блок комментария выглядит следующим образом (с помощью шаблонов):

{==============================================================================} 
Procedure Form1.DoSomething; 
{$region 'xmldoc'} 
///<summary></summary> 
///<author>skamradt</author> 
///<param name=''></param> 
///<returns></returns> 
///<exception cref=""></exception> 
///<since>2009-05-22</since> 
{$endregion} 
{------------------------------------------------------------------------------} 
begin 
    // code goes here. 
end;