Functional Options: Don't recommend closures#77
Merged
Conversation
This changes the Functional Options example to not recommend closures, instead favoring full implementations of the interface for each option. To help demonstrate that options don't have to be new types, I added a logger option to the example implemented around a `struct`. This made the examples too long so I dropped the timeout option: I wanted to keep cache around to demonstrate readability of naked booleans versus `WithCache(false)`. I renamed the function to Open to further reduce horizontal space consumed by the examples.
To keep the Bad/Good examples short and comparable, this change reduces the examples down to just the user-facing API and how it's used. The implementation is discussed separately in its own paragraph.
This aligns the usage examples for functional options Bad v Good in their own row in the table.
prashantv
reviewed
Dec 12, 2019
CHANGELOG.md
Outdated
| @@ -1,3 +1,8 @@ | |||
| # 2019-12-11 | |||
|
|
|||
| - Functional Options: Recommend individual implementations of `Option` | |||
Contributor
There was a problem hiding this comment.
I think Recommend struct implementations would be more accurate (some options may reuse the same struct)
style.md
Outdated
|
|
||
| </td><td> | ||
|
|
||
| Options must be provided only if needed. |
Contributor
There was a problem hiding this comment.
"must be provided" sounds a little odd, maybe just "Options are only provided if needed"
style.md
Outdated
| </tbody></table> | ||
| Note that there's a method of implementing this pattern with closures but we | ||
| believe that the pattern above provides more flexibility for authors and is | ||
| easier to debug for users. |
Contributor
There was a problem hiding this comment.
can we provide more details here?
- loss of comparisons (also makes mocks much harder)
- loss of string methods for pretty-printing
prashantv
approved these changes
Dec 17, 2019
mmelnyk
pushed a commit
to mmelnyk/guide
that referenced
this pull request
Oct 8, 2020
This changes the Functional Options example to not recommend closures, instead favoring full implementations of the interface for each option. To help demonstrate that options don't have to be new types, a logger option was added to the example. This made the examples too long so the the timeout option was dropped; cache was kept around to demonstrate readability of naked booleans versus `WithCache(false)`. Further, the function was renamed to Open and the Bad/Good side-by-side comparison was reduced to just the user-facing API. The implementation was moved to its own paragraph.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Per #74, this changes the recommendation for functional options to
suggest manual interface implementations instead of closures.
To make the example more demonstrative, I had to add a new option which
hurt the overall readability of the side-by-side comparison. This lead
to a minor reorganization: side-by-side includes user-facing API and
usage only, and implementation is demonstrated separately in its own
paragraph.
Resolves #74