Должен ли я прокомментировать объявление или определение в C ++?

Question

Что более удобно комментировать, объявление (в заголовочном файле) или определение (в исходном файле)? Может быть, я должен прокомментировать и то, или другое, и все это поместить в отдельный файл ...

Answer 1

Вы должны полностью задокументировать файл заголовка с наивысшим приоритетом.

Комментарии в определении должны быть сосредоточены на деталях реализации, в то время как комментарии заголовка должны быть сосредоточены на интерфейсе.

Третий источник документации, как вы предложили, также полезен. Следует описать общую концепцию.

Большим плюсом комментирования заголовочных файлов является то, что вы можете автоматически создавать из них документацию, если придерживаетесь простого синтаксиса. Скажи привет doxygen !

Answer 2

Я хочу добавить к ответу ypnos:

Откуда ваши комментарии, зависит от того, кто ваша аудитория. В этом отношении помогает думать о том, что ваш код является закрытым исходным кодом: сопровождающие получают возможность увидеть реализацию, а клиенты / пользователи видят только интерфейс. Если комментарий необходим пользователям, он должен войти в интерфейс. Если комментарий относится только к данной реализации, он, вероятно, должен входить только в реализацию (но не обязательно, в зависимости от вашей аудитории).

Answer 3

Зависит от того, что говорится в комментарии, и от того, кого вы ожидаете прочитать.