[doxygen] Комментарии в .h/.hpp/.. vs комментарии в .c/.cpp/...

предпочитаю в .java

Какая разница, на каком языке? Вопрос про doxygen.

Зачем загромождать хэдеры развёрнутыми комментариями и описаниями, если предполагается получать полную документацию по API простым путём (с помощью doxygen в твоём случае)? ".c/.cpp" однократно распарсятся во время компиляции, на выходе получишь библиотеку и доку по API. А хэдеры остаются неизменными - нафиг их такие громоздкие таскать в комплекте с библиотекой и парсить лишние килобайты какждый раз при сборке с библиотекой?

А что насчёт комментариев к полям?

Аргумент насчёт громоздкости принят — описания методов и классов/структур/enum'ов вынесу в cpp. А с полями что делать? Тоже выносить?

Кстати, насчёт выноса описаний классов/структур/enum'ов... немного пугает тот факт, что придётся поддерживать одинаковые названия в 2 местах

Ну, описания «классов/структур/enum'ов» придётся оставить в хэдерах - лишний «головняк» для синхронизации не нужен:(

то же, я так понял, верно и насчёт полей? или нынче все крутые перцы используют d-поинтеры и засирают хедеры уже в них?:)

Какий полей? Если полей структур/классов, то вместе с этими структурами классами.

Возможно, я плохо подумал перед тем как отвечать: мой ответ больше касался C, а в случае C++ бОльшую часть всё равно придётся описывать в хэдерах:(

полей классов, да...

Умные разработчики вообще мало комментируют - учатся код читать ) http://gaperton.livejournal.com/32772.html

Умные разработчики вообще мало комментируют - учатся код читать ) http://gaperton.livejournal.com/32772.html

Думаю к сокращениям RTFM, УМВР и т.д. можно добавить ЧКС.

Интерфейсы должны документироваться в файлах .h/.hpp

Реализации должны документироваться в .c/.cpp

> Интерфейсы должны документироваться в файлах .h/.hpp

В Qt и куче проектов не так.

Я все пишу в одном месте — в .h'никах. Чтобы можно было открыть и сразу понять что к чему. В .cpp файлах комментарии относящиеся к документации обычно не пишую.

Это каког же объема комментарии надо туда запихать, чтобы это сказалось на скорости сборки?

поменял коммент в хедере — должны пересобраться все о-шки, которые его подключают.

Очевидно, что комментарии обычно меняются при изменении интерфейса.

во время активного пиления ещё и во время исправлений и уточнений, например

В заголовках.

1) описанияй полей, структур (уже сказали)
2) документация имеет больше отношения к API, и независима от реализации

> Зачем загромождать хэдеры развёрнутыми комментариями и описаниями, если предполагается получать полную документацию по API простым путём (с помощью doxygen в твоём случае)? ".c/.cpp" однократно распарсятся во время компиляции, на выходе получишь библиотеку и доку по API. А хэдеры остаются неизменными - нафиг их такие громоздкие таскать в комплекте с библиотекой и парсить лишние килобайты какждый раз при сборке с библиотекой?

Что с вами? Старая трава уже не катит?

> Я все пишу в одном месте — в .h'никах. Чтобы можно было открыть и сразу понять что к чему. В .cpp файлах комментарии относящиеся к документации обычно не пишую.

Полностью согласен.

В хедерах, потому что это касается интерфейса, а не реализации.

С точки зрения комментариев мне очень понравились «лептоника» и gwyddion: в заголовочных файлах более-менее подробное описание структур, сишные файлы содержат общую информацию в «шапке» и сведения о назначении, аргументах и возвращаемом значении перед каждой функцией.