From 6cd0c88b48a99c068c87d096192ec5e04019e78b Mon Sep 17 00:00:00 2001 From: Paige Bailey Date: Thu, 28 May 2020 14:32:34 -0700 Subject: [PATCH 1/2] Updated "optional arguments" section. As discussed in the TF APIs Owners meeting on 27 May. --- governance/api-reviews.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/governance/api-reviews.md b/governance/api-reviews.md index 509dfd983..71acc0917 100644 --- a/governance/api-reviews.md +++ b/governance/api-reviews.md @@ -151,13 +151,18 @@ imperfections into new APIs for the sake of consistency with old APIs. ### Optional arguments with default values -Many APIs have optional arguments with a default value. Our recommendation is to -use `None` as the default value of any optional arguments and have the -implementation be responsible for handling it as opposed to using a default -value that directly represents the behavior (e.g. `aggregate='sum'`). The -latter prevents the implementation from distinguishing between the caller not -setting the argument vs. the caller setting the argument to the default value, -which may be needed when the default behavior is changing. +Many APIs have optional arguments that assign a default value (for example, `activation = None` +in [`tf.keras.layers.Dense`](https://www.tensorflow.org/api_docs/python/tf/keras/layers/Dense)). + +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 +distinguishing between the caller not setting the argument vs. the caller setting the +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. ### Does it belong in TF at all? From b1caad637126f1c0e4d5366072962a7d370226ae Mon Sep 17 00:00:00 2001 From: Paige Bailey Date: Mon, 24 Aug 2020 13:18:29 -0700 Subject: [PATCH 2/2] Update api-reviews.md --- governance/api-reviews.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/governance/api-reviews.md b/governance/api-reviews.md index 71acc0917..e8875f5d2 100644 --- a/governance/api-reviews.md +++ b/governance/api-reviews.md @@ -157,7 +157,7 @@ in [`tf.keras.layers.Dense`](https://www.tensorflow.org/api_docs/python/tf/keras 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 +the behavior (e.g. `num_threads = 10`). The latter prevents the implementation from distinguishing between the caller not setting the argument vs. the caller setting the argument to the default value, which may be needed when the default behavior is changing.