API design suggestion: rename UnmarshalOptions to Unmarshaler
stapelberg opened this issue · comments
Capturing this suggestion from @matttproud over in matttproud/golang_protobuf_extensions#22:
As a comment on the modern Protocol Buffer API, I find it rather strange that a type with "options" in the name does some imperative action versus being just configuration (e.g., an option/configuration struct/container). I could see taking protodelim.UnmarshalOptions and naming it protodelim.Unmarshaler or protodelim.Decoder. It's totally normal for types to accept configuration parameters directly, in which case having those fields in either of those two names would make sense. But seeing "options" makes it confusing, because few people would expect a type named "options" to be the meat of the business logic.
Seems like a reasonable change to me on first glance.
We should verify that type aliases like type protodelim.UnmarshalOptions = protodelim.Unmarshaler don’t have any adverse effects on performance/inlining (probably fine).
We should also do a quick survey to see how widely used the Options types are, and then judge the churn against the benefit.
Filing this here for now to give folks a chance to chime in.
As far as I understand, yeah, the type-alias wouldn’t introduce any overhead to performance or inlining. There’s already so much type aliasing in the standard library, that if it were a performance impact, then it should have been handled already.
You'd also want to rename the types in the proto, encoding/prototext, and encoding/protojson packages.
It's been a while, but I think we went with MarshalOptions/UnmarshalOptions, because the older proto package has proto.Unmarshaler and proto.Marshaler types that are interfaces describing a type which can marshal/unmarshal itself. Using a different name for the options type had less potential for confusion.
Renaming UnmarshalOptions and adding type UnmarshalOptions = Unmarshaler might not be a backwards-compatible change; I don't know how likely it is to cause breakage, but it will be user-visible to code using reflection to inspect types. If TGP and the ecosystem metrics pipeline report no problems, it's probably fine, though.
Personally, I'm dubious that the improvement is worth the churn. protodelim.UnmarshalOptions is probably not used much, but proto.UnmarshalOptions is.
FWIW: I found the "options"-laden names confusing when studying the new API. I literally asked myself as I was reading the APIs: "Options, but for what? What's taking them?"
Renaming MarshalOptions as Marshaler sounds fine to me as long as the naming convention is consistently applied.
I can't quite remember, but I believe @neild is correct that the pre-existing Marshaler and Unmarshaler types were why the name wasn't chosen. IIRC, we developed the v2 API within the v1 API, so name conflicts were possible during the transition. For prior precedence, the v1 "jsonpb" package has a Marshaler type that is effectively an options struct with actor methods hung off of it.