|
|
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
Kazantsev AlexeyЗа XML-доку в коде надо убивать. Лазарь хранит её отдельно. SVN-теги значит можно в исходники вставлять, а XML нельзя? :) Хотел бы я посмотреть примеры твоего реального кода, наверное бы даже индусы бы покраснели от него, не? чччДИксимел-док "для бедных", ничего хорошего, совсем. Главный плюс использования XML-документации в коде - единообразие описания классов/методов/типов/констант/т.д. всеми разработчиками проекта, что позволяет автоматически генерить документацию к исходникам. В своей карьере разработчика я видел миллионы вариантов оформления комментов к коду, а многие вообще считают ниже своего достоинства писать любые пояснения. Например индусы :) ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 12:56:15 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
asutp2... Главный плюс использования XML-документации в коде - единообразие описания классов/методов/типов/констант/т.д. всеми разработчиками проекта, что позволяет автоматически генерить документацию к исходникам. В своей карьере разработчика я видел миллионы вариантов оформления комментов к коду, а многие вообще считают ниже своего достоинства писать любые пояснения. Например индусы :) С тем, что хмл-док хоть как-то позволяет унифицировать документацию кода - полностью согласен, однако, не вполне понял насчет пользы автоматической генерации документации в условиях раздолбайского отношения разработчиков к оформлению кода (когда в коде нет этих самых комментариев). Имхо, автоматическая генерация доков по коду весьма полезна для создания скелета документации, но часто используется тогда, когда требуется наличие этих самых доков, но при этом никто сами доки читать не собирается ("требование ТЗ"). Впрочем, в последнем случае она тоже полезна. :) ... А если вспомнить, что пользователи лазаруса часто позиционируют себя как свободные художники, данная проблема для них таковой и не является... ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 14:12:08 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
asutp2SVN-теги значит можно в исходники вставлять, а XML нельзя? :) SVN'овскими тегами исходники не засираются. А после этой вашей XML-доки код читать невозможно. Особенно, когда вся декларация засрана такими полезными комментариями: Код: pascal 1. 2. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 17:22:38 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
Kazantsev Alexey, это исключительно твое субъективное мнение, что код становится не читаемым. Вполне читаем и глаз не режет. Плюс несет исключительно полезную информацию, которая может быть обработана любым генератором документации к исходникам (естественно, которые понимают разметку xml-документации и знают по pascal). Плюс выполняет унификацию комментариев в коде, чтобы каждый разраб в команде не писал их так, как вздумается. Вот мой маленький пример: Код: pascal 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. всё очевидно и понятно. В сгенерированной доке будет не только описание назначения типа, но и доп.инфа об особенностях, и ссылка на первоисточник. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 18:06:06 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
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. А если ещё читать не в иде, то вообще караул Код: plaintext 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. И это вместо простых и ясных нескольких строчек (легко читаемых даже без подсветки синтаксиса): Код: plaintext 1. 2. 3. 4. 5. 6. asutp2Плюс несет исключительно полезную информацию, которая может быть обработана любым генератором документации к исходникам (естественно, которые понимают разметку xml-документации и знают по pascal). Плюс выполняет унификацию комментариев в коде, чтобы каждый разраб в команде не писал их так, как вздумается. Всё то же самое достигается при внешнем хранении. Засирать код для этого не обязательно. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 18:21:36 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
asutp2, такое ощущение, что проиграв спор по существу предмета, ты пытаешься взять реванш хоть где-нибудь. ИМХО, у XML-доки свои задачи. Но при этом, она ничем не хуже или не лучше лазаревского способа документирования кода, вопрос удобства ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 18:33:04 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
Док, не, какой реванш, я необидчивый :) что касается возможностей лазаруса, я вполне справедливо сравниваю их с делфи ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 19:12:30 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
Согласен с тем, что xml-документация перезагружает код -- встречал несколько библиотек, где объявление классов-процедур тянулись на десятки страниц из-за слишком большого xml-описания, зачастую, формального (по факту полезного было от силы процентов 30%) -- очень неудобно было смотреть. Существуют различные инструменты, которые и по обычным комментариям в коде могут сгенерировать описание/заготовку. А уже после этого делается описание в этих самых инструментах вне делфи. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 23:17:20 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
JaDi, мне сложно представить тулзу, которая сможет понять произвольные комментарии и по ним построить описание. Согласен, что XML-документация значительно увеличивает секцию interface (на каждую строку определения свойства/метода и т.д. приходится несколько строк с xml-разметкой). Но, как я уже говорил выше, это позволяет всем разработчикам в команде делать описание единообразно, и это я считаю очень важный момент. Также ничто не мешает скрывать xml-разметку, каждая многострочная разметка сжимается в одну строку. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 23:47:03 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
asutp2, проблема автосгенерированной документации в том, что она ограничена по возможностям. В свое время эмба генерировала документацию для делфи (в период с делфи 2006 до какой-то там XE). Но это был такой отстой, что в конце концов они перешли на вики и еще несколько лет ее допиливали. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 13.08.2017, 23:52:41 |
|
||
|
XML-комментарии в коде
|
|||
|---|---|---|---|
|
#18+
asutp2мне сложно представить тулзу, которая сможет понять произвольные комментарии и по ним построить описание. Может. Например, Doc-O-Matic -- мощнейшая штука (буквально), но платная. Генерация заготовок в стиле современных справок и с использованием существующих комментариев в разном формате. Более того, сами комментарии и документацию может хранить как в исходниках, так и за их пределами. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 14.08.2017, 00:00:56 |
|
||
|
|

start [/forum/topic.php?fid=58&msg=39504570&tid=2041942]: |
0ms |
get settings: |
10ms |
get forum list: |
15ms |
check forum access: |
3ms |
check topic access: |
3ms |
track hit: |
184ms |
get topic data: |
9ms |
get forum data: |
2ms |
get page messages: |
49ms |
get tp. blocked users: |
1ms |
| others: | 225ms |
| total: | 501ms |

| 0 / 0 |
