Is it Worth Simplifying the Type, and Function Provider Naming?

[pavpen]

Hello, CGP community.

This may be a rather basic newbie question. (I'm slowly learning how to replace lengthy manual code with CGP patterns. Perhaps, a tutorial with small example projects like in The Rust Programming Language book would be helpful.)

I find the style of naming CGP providers as nouns like ActionPerformer, but the trait they annotate as an adjective phrase like CanPerformAction to introduce some language, and automation obstacles. For example:

#[cgp_component(WhatToNameThisProvider)]
pub trait CanListUsbDevices: HasErrorType + HasUsbDeviceListType {
    fn list_usb_devices(&self) -> Result<Self::UsbDeviceList, Self::Error>;
}

WhatToNameThisProvider?

• UsbDeviceLister: According to
  Context-Generic Programming Patterns (DRAFT) examples,
  this component's provider should be named something like UsbDeviceLister, except 'lister' in English doesn't have the expected meaning.
• UsbDeviceEnumerator: I could rename it to, e.g. UsbDeviceEnumerator. However, now the trait name (as well as the trait function name), and the provider trait name are more un-related. (It's harder for someone reading the code to find the trait for the provider, or vice versa).
• UsbDeviceEnumerator: I could rename the trait to CanEnumerateUsbDevices, and the trait function to enumerate_usb_devices, except that 'list' may be the expected name by API users, and renaming it may also make developers' work slower. (E.g., see
  'List' under 'Standard Methods' in §Retrieve a collection in the Google API Design Guide.)
  • UsbDeviceGetter: Other, API design guides may use 'get' instead of 'list' for the whole collection. However, UsbDeviceGetter now has a misleading name, since it sounds like an accessor for a single device.
  • UsbDevicesGetter: We can modify English grammar for the purposes of engineering to distinguish between an accessor for a single resource, and for a collection.

Sidebar on whether the above example should be an accessor

---

There could be some debate on whether the example trait above defines a getter, in which case it may look more like:

#[cgp_auto_getter]
pub trait HasUsbDevices: HasErrorType + HasUsbDeviceListType {
   fn usb_devices(&self) -> Result<Self::UsbDeviceList, Self::Error>;
}

However, a getter is often very cheap to execute, and the returned value doesn't usually change unless the API user,
calls a corresponding setter, or other modifying function. Since neither of these are true in this case (listing USB devices typically involves a kernel call, which has to suspend the current thread, and switch context; and devices can be plugged in, and unplugged, etc., which can change the returned list), I prefer to make this explicit by not making this look like an accessor. (This is admittedly my judgment.)

---

I think part of the issue is that what the CGP Patterns book calls a 'provider trait' seems to correspond more to what a user of a Dependency Injection framework may call an injectable service trait (or interface, if this was in an object-oriented language). (There's a similar issue with the naming of the cgp_component annotation macro.)

Wouldn't it be simpler to use a style like:

#[cgp_component(ListUsbDevicesService)] // Call it a service.
pub trait CanListUsbDevices: HasErrorType + HasUsbDeviceListType {
    fn list_usb_devices(&self) -> Result<Self::UsbDeviceList, Self::Error>;
}

Then the cgp_component macro can automate generating the 'provider trait' (or, 'service trait') name by appending Service to the name of the trait (and removing the Has, or Can prefix).

As another sidebar, according to examples from
Discuss naming conventions for traits,
traits that express the ability to perform an action are named without the Can prefix, at least in the standard library. (E.g., std::hash::Hash, or std::iter::Extend.) However, I do find where Context: CanListUsbDevices + HasErrorType very clear to read.

[soareschen]

Hi @pavpen, thanks for your feedback! Just as Rust don't force you to name traits a certain way, CGP as a library also don't enforce how you should name a provider or consumer trait.

Currently, the convention is that if there is no suitable noun, we add a Provider postfix to the provider trait. So you could for example name the provider trait as ListUsbDevicesProvider. You could also add a Impl postfix for it to become ListUsbDevicesImpl, or the Service postfix you suggested could work fine as well.

So feel free to choose whatever naming convention that suites you, especially during exploration phase. You can think about renaming the constructs later on, when your code is mature enough to be shared with others.

[pavpen]

Thanks, @soareschen for the quick reply.

I was thinking the struct that binds an injectable trait to an implementation may use the Provider suffix. I see you use that for the trait, which makes the naming more understandable to me now.

I was also confused by the name of the cgp_component macro, since the place where you see, e.g. a @Component annotation in Dagger, is where you bind a service interface to an implementation. In CGP that seems to be used to annotate the service trait instead.

(I'm also trying to get a clean way of associating a context struct with a struct from an existing API which I want to wrap in a CGP interface. But, I'll open a separate discussion, if I keep struggling.)