LINUX.ORG.RU
решено Форум — Development  

Где лучше размещать комментарии

 ,


0

3

Всем привет, использую для документирования кода doxygen, на гитхабе смотрел код обычно документируют в заголовках (*.h), но по мне так это не совсем удобно, понятно почему так делают, там просто описание функций и удобно наверное почитать про функцию именно там, но мне казалось удобнее в реализации уже комментарий создавать, т.к. помимо документации это еще и разделяет на функциональные блоки и код не сливается в один, хотя тут тоже можно что-то придумать. Или же лучше в заголовках писать кратикий комментарий через \brief, а в исходнике уже писать детальный комментарий?

★★★

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

annulen ★★★★★
()
Ответ на: комментарий от mashina

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

Int64 ★★★
() автор топика

А мне нравится (ИМХО, да) когда документация прямо в заголовочниках, как в ffmpeg, например. Можно читать в каком-нибудь Assistant, а можно нажать F2 на функции, потом PageUp и вот она документация прямо в редакторе...

Но таки да, для простыней а-ля кутешные DetailedDescription такой подход не годится.

Stil ★★★★★
()
Последнее исправление: Stil (всего исправлений: 1)
Ответ на: комментарий от Stil

Да у ffmpeg красиво оформлено все.

Int64 ★★★
() автор топика
Ответ на: комментарий от mashina

Лучше писать отдельно от кода или вообще не писать.

Отдельно от кода меньше шансов, что при изменении кода ты не забудешь поправить doxygen описания.

traffic
()
Ответ на: комментарий от traffic

Отдельно от кода меньше шансов, что при изменении кода ты не забудешь поправить doxygen описания.

А если вместе с кодом, то шансы что я вообще буду пытаться вычитывать гогнокод с мусорной маркировкой для doxygen и что-то править около нулевые. Делать документацию нужно только перед релизом и тогда ничего не забудешь. И за одно не будешь тратить просто так время на ненужные переписывания текстов в процессе разработки.

mashina ★★★★★
()
Ответ на: комментарий от mashina

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

peregrine ★★★★★
()

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

Да, *.h - это интерфейсная часть, и именно там _должно_ быть всё, необходимое для вызова функций/классов извне. Для опенсорса, конечно, это не так критично, как для проприетарщины, в крайнем случае можно и *.cpp посмотреть - но это именно крайний случай, не надо заставлять лезть в реализацию человека, которому для вызова нужен лишь интерфейс.

hobbit ★★★★★
()
Ответ на: комментарий от hobbit

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

Int64 ★★★
() автор топика

Я пишу в .cpp/.c файлах, ибо они так и так громоздкие, а нормальной IDE вообще пофиг откуда тянуть. Вообще в doxygen документация из заголовочного файла имеет меньший приоритет (т.е. если ты сделаешь ее и в хедере и в .cpp, то IDE или генератор документации или еще что-нибудь, что работает с doxygen, должно брать то, что ты написал в .cpp)

RiseOfDeath ★★★★
()
Ответ на: комментарий от mashina

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

А потом в команду приходит новый разработчик и офигевает с огромной вообще недокументированной проги.

RiseOfDeath ★★★★
()
Последнее исправление: RiseOfDeath (всего исправлений: 2)
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.
Development