Notes on header files

notes_on_header_files.md

Notes on header files

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. Inline implementation of functions, class method implementation, etc. goes into .inl headers or .cpp files.

For example .h file would contain only declaration and doxygen style documentation comment:

	/// Convert size in bytes to human readable string.
	void prettify(char* _out, int32_t _max, uint64_t _value)

Implementation if it's in .inl file would prefix function with inline:

	inline void prettify(char* _out, int32_t _max, uint64_t _value)
	{
		...
	}

Or if it's in .cpp file function would be implemented without inline:

	void prettify(char* _out, int32_t _max, uint64_t _value)
	{
		...
	}

This solves multiple issues. Immediately obvious one is that functions are trivially transferable between .inl and .cpp file with minimum modification, adding or removing inline keyword. Non-obvious part is that functions now can be declared in any order in .h file, it can be sorted by name, or grouped by some other logic, which improves documentation. You won't need to move whole functions around in some unnatural way just because functionA calls functionB. Documentation for functions is located in one place, it's easy to glance since function is one to a few lines of code. The only downside of this approach is that there is two places where function signature exist, which in case of inline functions wasn't the case.

Anyhow, it's not some huge discovery, rather notes since it's not common practice in C++ world.

.inl files aren't necessary here, you can put their content in header file itself.

@agauniyal You're an idiot that didn't read this at all but just left the comment... The whole point of this note is to not do that, rather put inline implementation somewhere else so that .h file is neat and easy to comprehend.

I've started moving to this too - but a large motivation being compile speed - particularly in the case of utility classes. As it's a lot quicker for the preprocessor to #include the now smaller, neater .h file than and not any weighty implementation details. Particularly for templates.
So I can declare a UtilityClass as a member of ContainingClass without feeling the guilt at #including lots of code every time ContainingClass.h is #included. ContainingClass.cpp will likely #include "UtilityClass.inl" but that just gets compiled the once.
Though I've not converted enough to get a time measurement as of yet.

@Weaseltron foobar.inl is included at the end of foobar.h, so the foobar.h is at least as big as before.