Poll: Deciding on The Specification Type Submodule Structure

[ghost]

Hey All!

Seems like most of the conversation in tpm-rs/project-wide-discussions#18 is about how to organize the types. To see what some of the other organization methods look like, I tried them out. I wanted to give them all a fair shake. I tried to come up with a list of 2 pros and 2 cons to keep things unbiased.

Please reply to this poll with your preferences!

I will leave this open for the 1 week, and then I will start heading in a direction based on the poll.

(1) By Prefixes (New File Per Type)

This was my orginal suggestion in tpm-rs/project-wide-discussions#18.

You create a new file per type and then you separate the types into submodules based on their common prefix.

Example: https://github.com/trent-reed/tpm-rs/tree/dev/trent-reed/restructuring/tpm2-rs-base/src/types

Pros

• Types are able to grow naturally if needed because they're already split into submodules (for example if we want to add detailed documentation or additional impls or type-specific tests).
• Types have very strict separation since they're each in different modules (can't accidentally depend on another type's private data or functions - should there be private data or functions).

Cons

• Creates many files and for simple types this can be excessive.
• You need to navigate around to find just about everything, since each file is one type - that might get annoying.

(2) By Prefixes (One File Per Prefix)

This is what @oddcoder suggested in tpm-rs/project-wide-discussions#18.

In this case we separate the types only by prefix, but we don't create any submodules past that.

Example: https://github.com/trent-reed/tpm-rs/tree/dev/trent-reed/restructuring-flat-prefixes/tpm2-rs-base/src/types

Pros

• Fewer files are created so less navigation to get to types (most types won't have special logic, so having a flat file of them might be appropriate).
• You can pretty easily make changes to types of the same prefix since they're all in the same file (if you're going to make big changes it's likely to impact all of a certain type by prefix).

Cons

• Harder to keep the types organized, and can become messier if we add documentation to types.
• Possible that two types can depend on each other's private functionality unexpectedly since they're in the same module (though addmittedly unlikely).

(3) By Prefixes (One File Per Prefix; Non-Trivial Types in New File)

This is what @oddcoder suggested in tpm-rs/project-wide-discussions#18.

This is just a special case of (2), where we split any types that have custom functionality not defined by a macro into a submodule (or as they start becoming large or unwieldy).

Example: https://github.com/trent-reed/tpm-rs/tree/dev/trent-reed/restructuring-flat-prefixes-for-simple/tpm2-rs-base/src/types

Pros

• Fewer files are created so less navigation to get to types (most types won't have special logic, so having a flat file of them might be appropriate).
• You can pretty easily make changes to types of the same prefix since they're all in the same file (if you're going to make big changes it's likely to impact all of a certain type by prefix).

Cons

• As we develop the types, it seems likely that we will just continue splitting these off until it basically becomes (1).
• It's a little harder to find spec types now, since some are in their own files and some are in the parent prefix module.

(4) By Suffix (New File Per Suffix)

This is what @bradlitterell mentioned in tpm-rs/project-wide-discussions#18.

In this case, we basically break the types up by their suffix instead of their prefix. This will cause related types to be located in the same file with one-another.

Example: https://github.com/trent-reed/tpm-rs/tree/dev/trent-reed/restructuring-flat-suffixes/tpm2-rs-base/src/types

Pros

• Types that relate to the same thing are organized closely together.
• Tests that depend on types by suffix will be able to be organized closely together.

Cons

• It's a big flat list of types by their suffix, which also feels excessive but maybe more-so because there's not an initial separation by prefix to make the list of submodules per module smaller.
• Types that have multiple associated types by their suffix likely also have special logic because they're complicated, which means we might anyways need to break types up further into even more submodules (submodules of submodules).

[ghost]

Okay, seems like it's basically just me and one other person who responded to this.

I'll bend towards option (3), so let me state the final expectations:

1. Simple types may be defined in the same module.
2. If the type has a manual (read: non-derived or non-macro-provided) implementation of a trait or an impl, it should go in its own separate submodule (for readability and organization purposes).
3. If the type has a custom impl provided by a macro_rules, it's allowed to be treated as-if it were derive-implemented, but we should keep the invocation of this macro close to the type definition to make it clear that they belong together.
4. If the type wants to keep some data (or function) private, and it's very urgent to ensure no other types have access to it, it may be a good reason to put it in a separate submodule.
5. Some of the other helper macros (like bitflag!) may be considered a macro-derived implementation, and thus won't need to be separated into submodules either - but keep the invocation of these macros close to the type definition.
6. If you want the client to access the type by pathing through a module by-name, then make the module pub and don't re-export the type. If not and you are just separating into another module for visibility or organizational purposes, don't make the module pub and instead re-export the types in the parent module.

So we can head towards an option (3) implementation; Separate specification types by prefixes, and put non-trivial types (per the above definition) in separate submodules (and expose it via a re-export).

Thanks everyone!

[ghost]

I can send out some PRs for this, leaving discussion open for folks in case there are any questions.