Skip to content

Consider removal of convenience methods from Component

Open

Description

This issue is taken from SpongePowered/SpongeAPI#2275 (comment)

Also note that this is somewhat linked to #222

TL;DR: The convenience methods on Component, such as style(...), color(...) etc. encourage bad habits and should be considered for removal in the next major release, or should be renamed to make it clear that they return a new immutable object.

For this, I'm mostly copy and pasting from the issue above.


Consider the two methods

Component.text();
Component.text(String);

These return two objects with a very important difference, one is mutable, one is not. And yet, both of these are valid ComponentLikes that can be used in many areas of Adventure:

Component.text().content("Text").color(NamedTextColor.GREEN).style(Style.style().decorate(TextDecoration.BOLD).decorate(TextDecoration.ITALIC).build());
Component.text("").content("Text").color(NamedTextColor.GREEN).decorate(TextDecoration.BOLD).style(Style.style(TextDecoration.BOLD).decoration(TextDecoration.ITALIC, TextDecoration.State.TRUE)); // slighly facetious with the starting method, but it proves a point

They look pretty much the same, and yet have completely different semantics. One is created from mutable builders, one is created from immutable objects. There is nothing to tell me which one I should use (I know it should be the first one) - part of why the lack of verbs is a problem. In the first method, I create three objects, the text component builder, the style builder and the style object (a fourth will be created upon use). The second method creates five - maybe more, I haven't looked at the implementation. For more complicated structures, this is only going to get worse. There should be some way to differentiate between what happens in both of these methods, and ideally, the latter should not exist at all. But there isn't. This is bad, and I am concerned it's going to hit a lot of people, and potentially going to cause a lot of mistakes.

Some thought needs to go into what is the "right" way to do things, and these need to be promoted. I do not know what the right way to do things is as it stands.

I personally think the convenience methods should be considered for removal. If that's not desired, I suggest prefixing the methods with with, in order to clarify that these methods are not the same as the builder variants.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Assignees

No one assigned

    Labels

    area: apistatus: needs discussionAn issue or PR that requires design decisions or further consensus building before it can be mergedAn issue or PR that requires design decisions or further consensus building before it can be mergedtype: question

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions