Right!

I’m with you on Doxygen. I find that showing the Doxygen comments in a header files hinders the readability of the class’s responsibilities, which are one of the main points of the header file. I hear some IDEs can fold the comments, but haven’t tried it personally.

I don’t know if I completely agree with that, but it does drive home the point that your code should be as self-documenting as possible.

What are your feeling on things like Doxygen for commenting? I’ve found that sometimes having explanations of functions and their inputs/outputs are helpful, but other times I’ve gotten annoyed at them. They sometimes explain very trivial things that are very obvious and only take up lots of space (5 lines or so for the Doxygen comment when the function itself is 1 or 2 lines).

I can see where always having comments in the file header to explain what that file is about could be useful. It seems when I’m explaining my code to someone, I always start with what the file is about… and I could just put that in the file header.

Thanks for your comment Bartolomiej, we’re in line here. And no I’ve never seen a 100% self documenting large project! But I found that the level of necessary documentation varies a lot though, even between large codebases.

Have you seen 100% self documented code? (In a larger project)