John Fremlin's blog: Documentation namespaces

Python packages have multiple names: the pip install name like scikit-learn then a name they are imported by, sklearn. Not to pick on Python, it's the same for other systems: in Java there is the jarfile name or Maven name like compile group: 'commons-io', name: 'commons-io' and then the import name like org.apace.commons.io. In C++ there is also no restriction on the namespaces a library might export.

When designing software it is super easy to come up with namespaces for nearly the same thing; for example, Docker logically has a distinction between images and containers. This makes sense but it's confusing. It means tools to manage these objects need to be created for each kind of object: there's a docker rm command to remove a container and a rmi command to remove an image.

One problem is introducing new concepts and kinds of things. There is a cost to that, borne by everybody who comes in contact with the system, and have to become familiar with new kinds of things and the relationships with them.

A second problem is that depending on context a name from one namespace may be preferred over another namespace but the context may not be clear between the person conveying the information and the person receiving. When metrics are emitted are they indexed under container or image? Sometimes it is clear which should be chosen and sometimes not.

Third, people have to painfully discover the relationship between names in different namespaces which may not be documented. To talk about a library in a build file you need to use one name and to import it another. Golang does a good job here by having a simple transformation between the names. In general, however, transformations like camelCase to snake_case where one or the other is used depending on context can be just as confusing as having multiple namespaces.