Этот баннер — требование Роскомнадзора для исполнения 152 ФЗ.
«На сайте осуществляется обработка файлов cookie, необходимых для работы сайта, а также для анализа использования сайта и улучшения предоставляемых сервисов с использованием метрической программы Яндекс.Метрика. Продолжая использовать сайт, вы даёте согласие с использованием данных технологий».
Политика конфиденциальности
|
|
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
Всем доброго времени суток. Хотел спросить, кто-как пишет доки по коду? К слову хорошее обсуждение получится. Сам хотел заюзать стиль из моей любимой Qt, но там описание какое-то странное - иногда они используют тег \fn, иногда нет. Что мне очень нравится - нет описания в h файле, тем самым они не замусоривают его. А вот в cpp - не на все методы есть описание, иногда оно идёт сразу за методом, иногда через \fn. Может кто поделится своей практикой ? ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 17.02.2014, 19:06 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
Я лично пользовался doxygen-ом. Не очень активно. Потому что я не очень верю в документацию на код. Ещё писал в ворде документы с описанием функций. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 17.02.2014, 19:11 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
Ещё писал модели в UML. И генерировал документацию по ним. Модели, естественно, были "сквозные", т.е. поддерживались во всё время разработки, и строились ещё до разработки. Т.е. модели были всегда первичны, код только вместе с моделью менялся. Так делал примерно проектов 5. Очень хорошо. Всё умерло со смертью Rose. (Rose как бы жива, только переродилась, и как ею теперь пользоваться -- не понятно). ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 17.02.2014, 19:14 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
PitBull, пользуюсь доксигеном, вот с этим утверждением не согласен: PitBullЧто мне очень нравится - нет описания в h файле, тем самым они не замусоривают егохидер - это декларация, там самое место описанию, чего, собственно, делает код. Когда пришло время заглядывать в .cpp то значит надо уже читать собственно код, а не его описание. Из за этой неприятной привычки норвежских самоделкиных проводил лишние долгие часы в отладке, в своё время. А любой современный редактор кода метит комментарии отдельным цветом, а некоторые, особо продвинутые, позволяют их свернуть, есичё )) ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 18.02.2014, 01:11 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
egorychPitBull, пользуюсь доксигеном, вот с этим утверждением не согласен: PitBullЧто мне очень нравится - нет описания в h файле, тем самым они не замусоривают егохидер - это декларация, там самое место описанию, чего, собственно, делает код. Когда пришло время заглядывать в .cpp то значит надо уже читать собственно код, а не его описание. Из за этой неприятной привычки норвежских самоделкиных проводил лишние долгие часы в отладке, в своё время. А любой современный редактор кода метит комментарии отдельным цветом, а некоторые, особо продвинутые, позволяют их свернуть, есичё )) хм, а если посмотреть на эту проблему по другому - если вы разработчик - открывайте документацию и читайте что делает код, но при этом методы часто называются интуитивно понятно, но и h файл не раздут, что сильно упрощает его чтение, ну а за деталями в доки? ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 19.02.2014, 11:27 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
PitBullхм, а если посмотреть на эту проблему по другому - если вы разработчик - открывайте документацию и читайте что делает код, но при этом методы часто называются интуитивно понятно, но и h файл не раздут, что сильно упрощает его чтение, ну а за деталями в доки?методы с интуитивно понятными названиями не требуют и больших комментариев, к примеру: Код: plaintext 1. 2. ну и сильно такие комментарии перегрузят хидер? Вся соль как раз в тех методах, которые не обладают интуитивно понятным названием, содержат неочевидный/сложный алгоритм, или имеют внутри побочные эффекты, вот их и надо документировать подробно, и желательно, имхо, там же, где находится их декларация. Потому что иногда удобно заглядывать в доку, довольно часто - в хидер, а уж совсем иногда, когда уже нет другого выбора - то в код. ...и тут вдруг ты обнаруживаешь, что есть комментарий, который кто-то забыл пометить тегом и он не попал в доку =)) ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 19.02.2014, 11:58 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
egorychPitBullхм, а если посмотреть на эту проблему по другому - если вы разработчик - открывайте документацию и читайте что делает код, но при этом методы часто называются интуитивно понятно, но и h файл не раздут, что сильно упрощает его чтение, ну а за деталями в доки?методы с интуитивно понятными названиями не требуют и больших комментариев, к примеру: Код: plaintext 1. 2. ну и сильно такие комментарии перегрузят хидер? Вся соль как раз в тех методах, которые не обладают интуитивно понятным названием, содержат неочевидный/сложный алгоритм, или имеют внутри побочные эффекты, вот их и надо документировать подробно, и желательно, имхо, там же, где находится их декларация. Потому что иногда удобно заглядывать в доку, довольно часто - в хидер, а уж совсем иногда, когда уже нет другого выбора - то в код. ...и тут вдруг ты обнаруживаешь, что есть комментарий, который кто-то забыл пометить тегом и он не попал в доку =)) Извините, я в начале не уточнил. Соль в том, что мне надо писать доки таким образом, чтобы по ним потом сгенерировать документацию для заказчика. Заказчик требует документацию, чтобы каждый метод был задокументирован =(( ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 19.02.2014, 12:25 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
Литературное программирование Правда, надо учитывать уровень и сферу деятельности автора. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 19.02.2014, 19:12 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
PitBull, если правильно понял вопрос, то я особо не парюсь пока: все функции/классы/переменные класса в хэдерах описываю с @brief/@note/@todo и мелочью вроде @a, но без спец-тегов аля fn. Реализация интерфейсов - с помощью блока с @name. На сам хэдер @file/@author с подробным описанием. Давно не пробовал, но вроде и так генерится приличная документация. В исходниках - обычные комментарии-простыни в большом количестве ну и @file опять же. Начальство считает, что в тяжком труде комментирования лучше перестраховаться :) В принципе особо глаз не раздражают эти самые простыни. А вот нервы здорово экономит, когда нужно править хитрый алгоритм годовалой давности. P.S. Ну и плюс ссылки на требования из ТЗ здорово помогают, но это уже собственная разработка, к доксигену отношения не имеющая. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 19.02.2014, 23:29 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
PitBullВсем доброго времени суток. Хотел спросить, кто-как пишет доки по коду? как-то так Код: plaintext 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 21.02.2014, 20:48 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
PitBullВсем доброго времени суток. Хотел спросить, кто-как пишет доки по коду? К слову хорошее обсуждение получится. Сам хотел заюзать стиль из моей любимой Qt, но там описание какое-то странное - иногда они используют тег \fn, иногда нет. Что мне очень нравится - нет описания в h файле, тем самым они не замусоривают его. А вот в cpp - не на все методы есть описание, иногда оно идёт сразу за методом, иногда через \fn. Может кто поделится своей практикой ? вот так писал в 200x году, http://agp1.hx0.ru/software/mlc.txt сделал конвертор старого документатора, на котором описана эта система, в латех. Теперь пишу на латехе. Разделы стараюсь к госту приближать, там все по теме. Введение в доксижен когда то для журнала hDrummer-а написал. http://agp1.hx0.ru/articles/dgIntro.pdf Эта пояснительная записка к проекту на QT http://agp1.hx0.ru/articles/pCst.pdf пысы это старые обсуждения данной темы. http://www.sql.ru/forum/32728/proektnaya-dokumentaciya-teo-tz-tp-soderzhanie-metody-i-sredstva?hl=???????????? ????????? http://www.sql.ru/forum/23646-1/kto-kak-pishet-dokumentaciu-k-svoim-netlenkam?hl=????????? ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 26.02.2014, 22:47 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
искренне_уважаемый_Репликант IMHO это бесполезное и порочное занятие писать комментарии в программных текстах. Хотя это, конечно, если нет визуальных моделей, например, тех же диаграмм деятельности или взаимодействия, к-рые описывают все взаимодействия между объектами и создаются при полноценном ООАП-подходе, например, как в RUP совершенно дурацкое утверждение. В идеальном случае, который лично мне не удавалось достичь /*в силу лени и не получения в свое время нужных навыков*/. Где то на шаге проектирования хорошо бы, чтобы было описание приложения на языке формальных спецификаций и этот текст вполне может служить комментариями в хедерах. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 26.02.2014, 22:54 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
картинки для начальства и наглядности должны создаваться как побочный продукт от аски текста языка формальных спецификаций. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 26.02.2014, 22:55 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
tchingizискренне_уважаемый_Репликант IMHO это бесполезное и порочное занятие писать комментарии в программных текстах. Хотя это, конечно, если нет визуальных моделей, например, тех же диаграмм деятельности или взаимодействия, к-рые описывают все взаимодействия между объектами и создаются при полноценном ООАП-подходе, например, как в RUP совершенно дурацкое утверждение.вот согласен )) И, помимо всего прочего, нарисовать все диаграммы, необходимые для проекта даже средней сложности занимает такое количество времени, что мама не горюй. А потом нудно это, ведь, диаграмки рисовать, куда приятней писать код ))) ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 26.02.2014, 23:03 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
egorych, эта, мы в программировании где-то обсуждали тулзу на javа, которая генерирует схему реляционных связей между таблицами по базе данных? ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 26.02.2014, 23:15 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
ну типа так Код: plaintext 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62. 63. 64. 65. 66. 67. 68. 69. 70. 71. 72. 73. 74. 75. 76. 77. 78. 79. 80. 81. 82. 83. 84. 85. 86. 87. 88. 89. 90. 91. 92. 93. 94. 95. 96. 97. 98. 99. 100. 101. 102. 103. 104. 105. 106. 107. 108. 109. 110. 111. 112. 113. 114. 115. 116. 117. 118. 119. 120. 121. 122. 123. 124. 125. 126. 127. 128. 129. 130. 131. 132. 133. 134. 135. 136. 137. 138. 139. 140. 141. 142. 143. 144. 145. 146. 147. 148. 149. 150. 151. 152. 153. 154. 155. 156. 157. 158. 159. 160. 161. 162. 163. 164. 165. 166. 167. 168. 169. 170. 171. 172. 173. 174. 175. 176. 177. 178. 179. 180. 181. 182. 183. 184. 185. 186. 187. 188. 189. 190. 191. 192. 193. 194. 195. 196. 197. 198. 199. 200. 201. 202. 203. 204. 205. 206. 207. 208. 209. 210. 211. 212. 213. 214. 215. 216. 217. 218. ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 26.02.2014, 23:18 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
ой блин, сорри White Owl, MasterZiv, mayton в спойлер возьмите плиз ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 26.02.2014, 23:20 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
tchingizegorych, эта, мы в программировании где-то обсуждали тулзу на javа, которая генерирует схему реляционных связей между таблицами по базе данных?не помню, честно (( ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 26.02.2014, 23:41 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
tchingizegorych, эта, мы в программировании где-то обсуждали тулзу на javа, которая генерирует схему реляционных связей между таблицами по базе данных? вспомнил , оно? ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 27.02.2014, 01:17 |
|
||
|
Написание документации dOxygen
|
|||
|---|---|---|---|
|
#18+
схемаспай. Два раза забывал её попробовать. Программы для построения графа зависимостей блин. за какието два часа както началось запускаться, но на склайте сбоит и собственно схему связей не рисует. закладка на релейшеншип пустая. Руки не с того места ростут ... |
|||
|
:
Нравится:
Не нравится:
|
|||
| 27.02.2014, 01:35 |
|
||
|
|

start [/forum/topic.php?fid=57&msg=38573591&tid=2019652]: |
0ms |
get settings: |
8ms |
get forum list: |
13ms |
check forum access: |
3ms |
check topic access: |
3ms |
track hit: |
64ms |
get topic data: |
7ms |
get forum data: |
2ms |
get page messages: |
51ms |
get tp. blocked users: |
1ms |
| others: | 14ms |
| total: | 166ms |

| 0 / 0 |
