Notes on header files

This article was originally published as a gist here.
After over 20 years working with C/C++ I finally got clear idea how header files need to be organized. Most of the projects in C++ world simply dump everything in .h file, and most of my C++ code was organized this way. Lately I started to separate function declaration from implementation as it was done in C. Now .h headers are exclusevely intended for function and class declaration with doxygen documentation style comments.