diff --git a/governance/api-reviews.md b/governance/api-reviews.md index 509dfd983..e8875f5d2 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. `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. + +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?