Should I put all header files inside the include dir?

edit

This will be an opiniated answer, but just to provide you with my own insight / experience:

Now I'm getting started with ROS and I see quite a few packages that seem to put .h files in include and .cpp files in src. Is there are specific reason to do this?

include directories are only exported (ie: added to the public interface of a ROS package) if that directory is explicitly passed to the catkin_package(.. INCLUDE_DIRS ..) call as an argument. Packages which have no headers that should be part of the public interface should not do this. Packages which just provide 'top level' nodes, but no libraries are examples of pkgs that should probably not have their include directory exposed by catkin_package(..).

So if we accept that, any header in $pkg_dir/include (or any other folder with headers that is passed to catkin_package(..)) always defines the public interface of a package. And inverting this: $pkg_dir/include should only contain headers that are intended to be part of that same public interface (again: assuming that $pkg_dir/include is actually passed to catkin_package(..)).

Now as to whether this 'best practice' is adopted by the ROS community as a whole I cannot say. It is however how I've structured my packages, and it works well for me.

I believe this would align with what you already wrote yourself: only add public headers to a publicly-visible include folder, and keep the rest private. So I would recommend you to keep doing what you already have been doing, and consider the $pkg_dir/include directory as the default location for the public interface of any/your package(s).