What is the reason behind completely hiding implementations in the API?

edit

The coding style guide discusses using virtual interfaces for classes such that the interface is exposed but the implementation is hidden.

I understand the use of this in simplifying the API, but this can be cumbersome when I want to make modifications and changes.

For example, the cv::cuda::pyrLKSparseOpticalFlow code. It has a virtual interface and then a hidden implementation which is created with createPyrLKSparseOpticalFlow.

Why not have an exposed implementation that is in a header that isn't necessarily included with the module level cudaOptFlow.hpp header? So we could have something like:

• cudaOptFlow.hpp

• cudaOptFlow

-- pyrLKOptFlow.hpp <-- interface, included by cudaOptFlow.hpp

-- pyrLKOptFlow_impl.hpp <-- implementation, not included by cudaOptFlow.hpp

By exposing the interface in this fashion, I can optionally access and inherit from the implementation. When including the top level cudaOptFlow.hpp file, only the interface is exposed and the creation function. So it should be just as fast to compile code using the interface.

I can see why using the implementation could be problematic with the two first points of the coding style guide:

• We want our API to stay stable when the implementation changes.

• We want to preserve not only source-level compatibility, but binary-level compatibility as well.

But I believe using just the interface should achieve this, and I think the application developer should have the choice of using the implementation and dealing with updating things accordingly if he wants the extra control.