Updated "optional arguments" section. #250
Open
Conversation
This file contains 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
As discussed in the TF APIs Owners meeting on 27 May.
karmel
reviewed
May 28, 2020
| argument to the default value, which may be needed when the default behavior is changing. | ||
|
|
||
| If the optional argument is _backwards incompatible to change_, however, its default should | ||
| reflect the actual default value when possible. |
There was a problem hiding this comment.
Can we include @fchollet 's Milk example as well? I rather like that as a way to differentiate the two. In code would be ideal, so we can show what we mean by letting the implementation set the value.
There was a problem hiding this comment.
The activation function or aggregation is a good example of something backwards incompatible and should be here
alextp
suggested changes
May 28, 2020
| argument to the default value, which may be needed when the default behavior is changing. | ||
|
|
||
| If the optional argument is _backwards incompatible to change_, however, its default should | ||
| reflect the actual default value when possible. |
There was a problem hiding this comment.
The activation function or aggregation is a good example of something backwards incompatible and should be here
governance/api-reviews.md
Outdated
| Our recommendation is to use `None` as the default value for _any optional arguments | ||
| that may be adjusted or changed over time_, and have the implementation be responsible | ||
| for handling the value, as opposed to using a default value that directly represents | ||
| the behavior (e.g. `aggregate='sum'`). The latter prevents the implementation from |
There was a problem hiding this comment.
Maybe mention num_threads=10 instead of aggregate=sum? That's more in keeping with stuff that can obviously change (changing the aggregation is incompatible)
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
As discussed in the TF APIs Owners meeting on 27 May.