Naming Conventions

[malliaridis]

After studying a while Decompose's sample projects I saw that they are all following the same naming conventions, which I find awesome. However, I have sometimes difficulties to define the right verb or name for specific classes of Intents, Labels , Actions and Messages.

Would it be a good idea to work on a standardization / guide for the naming conventions for Decompose-specific objects? I would like to have something I can look for when I write or review code.

[arkivanov]

This sounds like more related to MVIKotlin, isn't it? Let me know, so I could transfer it there.

Here is a general guide.

• Intent - it is a call to action, so should normally be a verb in imperative mood (e.g. Intent.LoadData, Intent.Refresh, Intent.SetItems(...), etc.).
• Action - basically the same as Intent, but internal in a Store.
• Message - is abstract by design, you can use whatever name for it (e.g. Message.Error, Message.ClearItems, Message.DataLoaded, etc.).
• Label - is also abstract, similar to Message, but public in a Store.

[malliaridis]

That's interesting. 🤔 It seems like I have been doing something wrong / differently.

I recommend to not add any special suffixes, because it add semantics of how a component is used.

Because I cannot imagine how that could look like in practice, could you explain that in a few words with the contacts example? Like, having an overview with a contacts list and the option to display, create or edit a contact, what components would you likely use?

The way I understand your recommendation is that you would use a single component for all of that, but that would be confusing because of too many state properties. My approach would be to split the component into multiple child components and export related functionality in individual components. Additionally, I would move components that are supposed to be used in other places too in a core package or make them publicly available. That's why I would use a suffix and add semantics to specific components.

And about the naming you mentioned, this would solve a few naming problems I had in the previews where I called the elements the same way or had conflicts with data models. 😅

[arkivanov]

For the Contacts feature there could be the following components:

ContactsComponent - the root of the contacts feature (if needed)
ContactListComponent - a list of contacts
ContactDetailsComponent - details of a contact
EditContactComponent (or ContactEditComponent) - editing (or creating) a contact
CreateContactComponent (or ContactCreateComponent) - if you need separate components for creating and editing

Now, you can easily extract (or add) additional child components, and you don't need to change the existing names. For instance, you may want to extract something like ContactHeaderComponent from ContactDetailsComponent, that would display e.g. an avatar and some brief information of a contact. Or for example there could be FriendListComponent, etc.

And about the naming you mentioned, this would solve a few naming problems I had in the previews where I called the elements the same way or had conflicts with data models.

That's exactly the reason.

[malliaridis]

Ok, I got your previous message completely wrong then. 😅 So the problem was about the naming of child and parent components. That makes completely sense now. So no child / parent related words for naming. That's a good point I haven't thought about. Thanks a lot. 😄

Do you think there is any value in creating a page for those naming conventions?

[arkivanov]

Yeah, it definitely makes sense for MVIKotlin, and perhaps for Decompose as well. But this should be a recommendation, not a "coding convention".

[malliaridis]

I agree. Such things should only be recommended, never forced.

[azlekov]

On the naming convention topics - how to you manage the names of callback or actions?

Across the project I have a lot of interface methods and later on params like:

onBackPressed, onDetailsPressed, onAddClicked etc. and I end up with a lot of:

I did not find a way to have the same name on the Component interface and what to pass as Component constructor param.

Do you use any convention here? Thanks!

[azlekov]

Are you wrapping multiple actions into objects instead passing 3-4 params to the component constructor?

[arkivanov]

There are no particular conventions here.

You can have the same name for the method and callback, you will need to call the callback as:

override fun onAddClicked() {
    onAddClicked.invoke()
}

You may also find the following pattern useful.

interface SomeComponent {
    val onAddClicked: () -> Unit
}

class DefaultSomeComponent(
    override val onAddClicked: () -> Unit,
) : SomeComponent

The first option allows additional logic before or after calling the actual callback. Whereas the second option saves some LOCs.

Personally, I prefer UI-related function names in component interfaces - e.g. "clicked", "pressed", etc. And something UI-agnostic in callback names. For example:

interface SomeComponent {
    fun onAddUserClicked()
    fun onItemClicked()
    fun onLoginClicked()
}

class DefaultSomeComponent(
    val onAddUser: () -> Unit,
    val onItemSelected: () -> Unit,
    val onLoginRequested: () -> Unit,
) {
    // ...
}

[aartikov]

I like to create sealed interface for outputs of the component. For example:

interface SomeComponent {
    fun onAddUserClicked()
    fun onItemClicked()
    fun onLoginClicked()

    sealed interface Output {
        object AddUser: Output
        object ItemSelected: Output
        object LoginRequested: Output
    }
}

class DefaultSomeComponent(
    val onOutput: (SomeComponent.Output) -> Unit
) {
    // ...
}