[C++] The difference between namespace detail and internal

[arashandishgar]

Describe the usage question you have. Please include as many useful details as possible.

I found that Arrow uses two groups of namespace for separating APIs from the public the names of which are internal and detail. What's the difference between them?

Component(s)

C++

[kou]

@pitrou Do you have any preference? It seems that the Google C++ Style Guide uses internal not detail:

https://google.github.io/styleguide/cppguide.html#Namespaces

Use namespaces with "internal" in the name to document parts of an API that should not be mentioned by users of the API.

[pitrou]

I think that I've used detail for implementation details that leak into public APIs (for example, a base class for public API classes). No strong feeling from me, though. We could perhaps make our conventions simpler.

@felipecrv @bkietz What do you think?

[bkietz]

My understanding has always been that detail implies "shouldn't be necessary for users" while internal implies "danger for users".

I think it'd be fine to just use internal for anything we don't intend users to touch

[felipecrv]

My understand has always been arrow::internal can leak into headers, but arrow::detail is for details within a .cc (compilation unit).

arrow::internal APIs MUST be present in headers because to implement public APIs across different .cc files, we need the internal APIs.

Number of .h and .cc where these names occur:

~/code/arrow (main)$ ag "\bdetail\b" -l | egrep "\.cc$" | wc -l
      50
 ~/code/arrow (main)$ ag "\bdetail\b" -l | egrep "\.h$" | wc -l
      46
~/code/arrow (main)$ ag "\binternal\b" -l | egrep "\.h$" | wc -l
     304
 ~/code/arrow (main)$ ag "\binternal\b" -l | egrep "\.cc$" | wc -l
     600

Which is very similar to @bkietz explanation:

detail = unnecessary for users
internal = danger, but might be necessary