Documenting code header and source [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 8 years ago.

Improve this question

It's a simple question. I'm documenting my code following the documentation of the Doxygen, but I have a question: Where I need to document? On the header, on the source or both of them? I know that this is not a rule, but I want to know your opinion about this and what you do on your code and why you do that. For example: I'm documenting the header, and it's nice, the appearance of the code increased, but when I look the source (.cpp) file, I got scared, because there's no documentation and the code is not beautiful, I mean, not the logic, but in beauty (indentation). And everybody knows that even though the code not beautiful (which is difficult in C++) with a documentation it get coolest and easier to read.

Thank you all. (And remember, before you start writing a moral lesson, know that I know that it's not a rule, I'm just wondering what you do)

Answer 1

Personally I prefer documenting the h file with that sort of thing. People who need to use your APIs might need your header, but not your cpp. People will never need your cpp without the header. Keep the documentation in one place where everyone who needs it gets it.