Drake: Should Namespace drake::systems::plants::joints Be Flattened?

[liangfok]

In #3358, @david-german-tri noted that namespace drake::systems::plants::joints was relatively verbose. Should it be flattened by, for example, promoting "plants" to be a child of "drake"? Ideally, the directory structure and even the exported libraries should be updated to match the namespaces.

[sherm1]

I think it is a mistake to attempt to duplicate the directory structure (which is useful for organizing files) in the namespace structure (which pollutes every use in the code for eternity). I suggest that we stop namespacing the API at 2 or 3 levels max, even if the directory structure goes deeper.

[liangfok]

OK, how about let's make the rule "prefer to make name spaces match directory structure"? That way we can always violate it as needed. I think having the directory structure not match the name spaces introduces a non-zero amount of cognitive dissonance that should be easily avoidable.

Since the objects in drake/systems/plants are systems, should they be moved into drake/plants?

[jwnimmer-tri]

I see no reason to make a correspondence rule (or stated preference) about directories vs namespaces, beyond what cppguide already says. ("_Namespaces should have unique names based on the project name, and possibly its path._")

I disbelieve that the confusion related to namespaces and directories differing is due to their mismatch. Rather, I assert that it's due to the directory structure being confusing in the first place. Propagating that confusion to the namespaces only makes it worse. I would rather us focus our efforts on first fixing the physical organization of the source code, and then secondly consider if the namespace rules require further refinement.

[david-german-tri]

@jwnimmer-tri says exactly what I meant, but more eloquently. The bulky, confusing namespace is evidence that the physical organization is wrong. (Given the physical organization that we have, it's better than any other in-style namespace I could think of, hence my LGTM on #3358.)

[liangfok]

So, once the directory structure makes logical sense, should we then prefer to make the name spaces match the directory structure? Perhaps in the intermediate term, we should "prefer that directory structure match the name spaces" since presumably the name spaces are more flexible and thus can be made to make sense sooner?

[jwnimmer-tri]

So, once the directory structure makes logical sense, should we then prefer to make the name spaces match the directory structure?

Nope. By way of counter-example: in drake/common/*, we use namespace drake. In drake/systems/framework*, we use namespace drake::systems. The namespace (which is pervasive throughout our APIs) casts a wider net than the directory structure (which embodies implementation details).

[liangfok]

OK, so going back to the original topic of this issue, should namespace drake::systems::plants::joints be shortened and if so how?

[jwnimmer-tri]

Use the shortest namespace that disambiguates the names within it. drake::joints perhaps for now.

I suspect that the longer-term answer is a better reorg of the files in drake/systems/plants to capture the highly-coupled/cohesive RigidBody body of work into its own separate library, at which point its drake::rigidbody to encompass the whole family.

Or just leave it alone for now, fix the file location and library grouping, and then fix the namespaces.

[liangfok]

OK thanks. I will close this issue until after the files in drake/systems/plants are reorganized.