powered by simpleCommunicator - 2.0.61     © 2026 Programmizd 02
Целевая тема:
Создать новую тему:
Автор:
Закрыть
Цитировать
Форумы / Delphi [игнор отключен] [закрыт для гостей] / XML-комментарии в коде
11 сообщений из 11, страница 1 из 1
XML-комментарии в коде
    #39504558
asutp2
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Kazantsev AlexeyЗа XML-доку в коде надо убивать. Лазарь хранит её отдельно.
SVN-теги значит можно в исходники вставлять, а XML нельзя? :) Хотел бы я посмотреть примеры твоего реального кода, наверное бы даже индусы бы покраснели от него, не?
чччДИксимел-док "для бедных", ничего хорошего, совсем.
Главный плюс использования XML-документации в коде - единообразие описания классов/методов/типов/констант/т.д. всеми разработчиками проекта, что позволяет автоматически генерить документацию к исходникам. В своей карьере разработчика я видел миллионы вариантов оформления комментов к коду, а многие вообще считают ниже своего достоинства писать любые пояснения. Например индусы :)
...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504570
чччД
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
asutp2...
Главный плюс использования XML-документации в коде - единообразие описания классов/методов/типов/констант/т.д. всеми разработчиками проекта, что позволяет автоматически генерить документацию к исходникам. В своей карьере разработчика я видел миллионы вариантов оформления комментов к коду, а многие вообще считают ниже своего достоинства писать любые пояснения. Например индусы :)
С тем, что хмл-док хоть как-то позволяет унифицировать документацию кода - полностью согласен, однако, не вполне понял насчет пользы автоматической генерации документации в условиях раздолбайского отношения разработчиков к оформлению кода (когда в коде нет этих самых комментариев).

Имхо, автоматическая генерация доков по коду весьма полезна для создания скелета документации, но часто используется тогда, когда требуется наличие этих самых доков, но при этом никто сами доки читать не собирается ("требование ТЗ"). Впрочем, в последнем случае она тоже полезна. :)
...
А если вспомнить, что пользователи лазаруса часто позиционируют себя как свободные художники, данная проблема для них таковой и не является...
...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504606
Kazantsev Alexey
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
asutp2SVN-теги значит можно в исходники вставлять, а XML нельзя? :)
SVN'овскими тегами исходники не засираются. А после этой вашей XML-доки код читать невозможно. Особенно, когда вся декларация засрана такими полезными комментариями:
Код: pascal
1.
2.
    /// <summary>Specifies the width of the item. </summary>
    property Width: Integer read GetWidth write SetWidth;
...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504613
asutp2
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Kazantsev Alexey,

это исключительно твое субъективное мнение, что код становится не читаемым. Вполне читаем и глаз не режет.
Плюс несет исключительно полезную информацию, которая может быть обработана любым генератором документации к исходникам (естественно, которые понимают разметку xml-документации и знают по pascal).
Плюс выполняет унификацию комментариев в коде, чтобы каждый разраб в команде не писал их так, как вздумается.

Вот мой маленький пример:

Код: pascal
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
  
  /// <summary>
  ///   Параметры RAS-соединения для Windows 2000 и более поздних версий (Unicode версия)
  /// </summary>
  /// <remarks>
  ///   В связи с требованием Win64 выравнивание структуры RasConn выполняется на двойное слово
  /// </remarks>
  /// <seealso href="https://msdn.microsoft.com/en-us/library/aa376725(v=vs.85).aspx">
  ///   MSDN
  /// </seealso>
  TRasConn2K = record



всё очевидно и понятно. В сгенерированной доке будет не только описание назначения типа, но и доп.инфа об особенностях, и ссылка на первоисточник.
...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504622
Kazantsev Alexey
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
asutp2Вполне читаем и глаз не режет.
Угу
Код: pascal
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
    /// <summary>
    /// Instantiates an IXMLDOMDocument from the MSXML runtime.
    /// Override this method to have full control over IXMLDOMDocument CoClass creation.
    /// </summary>
    class function CreateDOMDocument: IXMLDOMDocument; virtual;
    /// <summary>
    /// Initializes the list of possible IXMLDOMDocument CoClass GUIDS to create.
    /// The default list includes multiple versions of MSXML (6.0 down to 2.6).
    /// </summary>
    class procedure SetDOMDocumentCoClasses(GuidList: array of TGUID);
    /// <summary>
    /// Adds a DOM property to the DOMProperties list. Example call:
    ///  Xml.Win.msxmldom.MSXMLDOMDocumentFactory.AddDOMProperty('ProhibitDTD', False, True);
    /// </summary>
//    class procedure AddDOMProperty(const PropName: WideString; PropValue: OleVariant;
    class procedure AddDOMProperty(const PropName: DomString; PropValue: OleVariant;
      UpdateExisting: Boolean = True);
    /// <summary>
    /// List of DOMProperties to be set on the IXMLDOMDocument after it is created.
    /// See MSXML Second-Level DOM Properties in the MSDN documentation for details.
    ///  http://msdn.microsoft.com/en-us/library/windows/desktop/ms766391(v=vs.85).aspx
    /// </summary>
    class property DOMProperties: TDOMPropertyList read FDOMProperties write FDOMProperties;


А если ещё читать не в иде, то вообще караул
Код: plaintext
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
    /// <summary>
    /// Instantiates an IXMLDOMDocument from the MSXML runtime.
    /// Override this method to have full control over IXMLDOMDocument CoClass creation.
    /// </summary>
    class function CreateDOMDocument: IXMLDOMDocument; virtual;
    /// <summary>
    /// Initializes the list of possible IXMLDOMDocument CoClass GUIDS to create.
    /// The default list includes multiple versions of MSXML (6.0 down to 2.6).
    /// </summary>
    class procedure SetDOMDocumentCoClasses(GuidList: array of TGUID);
    /// <summary>
    /// Adds a DOM property to the DOMProperties list. Example call:
    ///  Xml.Win.msxmldom.MSXMLDOMDocumentFactory.AddDOMProperty('ProhibitDTD', False, True);
    /// </summary>
//    class procedure AddDOMProperty(const PropName: WideString; PropValue: OleVariant;
    class procedure AddDOMProperty(const PropName: DomString; PropValue: OleVariant;
      UpdateExisting: Boolean = True);
    /// <summary>
    /// List of DOMProperties to be set on the IXMLDOMDocument after it is created.
    /// See MSXML Second-Level DOM Properties in the MSDN documentation for details.
    ///   http://msdn.microsoft.com/en-us/library/windows/desktop/ms766391(v=vs.85).aspx 
    /// </summary>
    class property DOMProperties: TDOMPropertyList read FDOMProperties write FDOMProperties;

И это вместо простых и ясных нескольких строчек (легко читаемых даже без подсветки синтаксиса):
Код: plaintext
1.
2.
3.
4.
5.
6.
    class function CreateDOMDocument: IXMLDOMDocument; virtual;
    class procedure SetDOMDocumentCoClasses(GuidList: array of TGUID);
//    class procedure AddDOMProperty(const PropName: WideString; PropValue: OleVariant;
    class procedure AddDOMProperty(const PropName: DomString; PropValue: OleVariant;
      UpdateExisting: Boolean = True);
    class property DOMProperties: TDOMPropertyList read FDOMProperties write FDOMProperties;

asutp2Плюс несет исключительно полезную информацию, которая может быть обработана любым генератором документации к исходникам (естественно, которые понимают разметку xml-документации и знают по pascal).
Плюс выполняет унификацию комментариев в коде, чтобы каждый разраб в команде не писал их так, как вздумается.
Всё то же самое достигается при внешнем хранении. Засирать код для этого не обязательно.
...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504628
Фотография Док
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
asutp2,

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

ИМХО, у XML-доки свои задачи. Но при этом, она ничем не хуже или не лучше лазаревского способа документирования кода, вопрос удобства


...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504633
asutp2
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Док,

не, какой реванш, я необидчивый :)
что касается возможностей лазаруса, я вполне справедливо сравниваю их с делфи
...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504694
Фотография JayDi
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
Согласен с тем, что xml-документация перезагружает код -- встречал несколько библиотек, где объявление классов-процедур тянулись на десятки страниц из-за слишком большого xml-описания, зачастую, формального (по факту полезного было от силы процентов 30%) -- очень неудобно было смотреть.

Существуют различные инструменты, которые и по обычным комментариям в коде могут сгенерировать описание/заготовку. А уже после этого делается описание в этих самых инструментах вне делфи.
...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504705
asutp2
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
JaDi,

мне сложно представить тулзу, которая сможет понять произвольные комментарии и по ним построить описание.

Согласен, что XML-документация значительно увеличивает секцию interface (на каждую строку определения свойства/метода и т.д. приходится несколько строк с xml-разметкой). Но, как я уже говорил выше, это позволяет всем разработчикам в команде делать описание единообразно, и это я считаю очень важный момент. Также ничто не мешает скрывать xml-разметку, каждая многострочная разметка сжимается в одну строку.
...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504706
Фотография JayDi
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
asutp2,

проблема автосгенерированной документации в том, что она ограничена по возможностям. В свое время эмба генерировала документацию для делфи (в период с делфи 2006 до какой-то там XE). Но это был такой отстой, что в конце концов они перешли на вики и еще несколько лет ее допиливали.
...
Рейтинг: 0 / 0
XML-комментарии в коде
    #39504708
Фотография JayDi
Скрыть профиль Поместить в игнор-лист Сообщения автора в теме
Участник
asutp2мне сложно представить тулзу, которая сможет понять произвольные комментарии и по ним построить описание.
Может. Например, Doc-O-Matic -- мощнейшая штука (буквально), но платная. Генерация заготовок в стиле современных справок и с использованием существующих комментариев в разном формате. Более того, сами комментарии и документацию может хранить как в исходниках, так и за их пределами.

...
Рейтинг: 0 / 0
11 сообщений из 11, страница 1 из 1
Форумы / Delphi [игнор отключен] [закрыт для гостей] / XML-комментарии в коде
Найденые пользователи ...
Разблокировать пользователей ...
Читали форум (0):
Пользователи онлайн (0):
x
x
Закрыть


Просмотр
0 / 0
Close
Debug Console [Select Text]