Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Resource API: constructors suffice for the Create API #191

Closed
wants to merge 1 commit into from
Closed

Resource API: constructors suffice for the Create API #191

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion specification/resources-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ labels"](../semantic-conventions.md) that have prescribed semantic meanings.
### Create

Creates a new `Resource` out of the collection of labels. This is a static
method.
method. For object-oriented languages, a constructor is also valid.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a benefit for APIs to use static factory methods instead of ctor. See this article about java (also I think applies to other object-oriented languages) https://javarevisited.blogspot.com/2017/02/5-difference-between-constructor-and-factory-method-in-java.html

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the link! I think that does provide great arguments for why a factory method works well.

What's the best way to add this insight to the spec? should we explicitly call out some of the advantage / disadvantages, or defer to a larger document discouraging constructors?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we shouldn't enforce factory methods usage - recommending them should be fine though.

(I get the advantages of factory methods, but I'd prefer to offer some flexibility here, honestly)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not saying that we should enforce that, but I want everyone to understand the tradeoffs when they make a language specific decision. May be good to say that:
"we recommend factory method for these reasons a, b, c, but a direct constructor can be also used."

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This argument can be a generic comment that applies to all the ctor/static factory method (methods to create object in general), and in this specific way I would just say:

API MUST allow users to create a new Resource from a collection of labels.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"we recommend factory method for these reasons a, b, c, but a direct constructor can be also used."

This would be fine, yes ;)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think given the focus on capabilities, it might be more productive to have a PR around using a capabilities tone, although I plan on incorporating all the feedback from here.

I'll close this PR and start another one up around adhering to #165.


Required parameter:

Expand Down