Recommend that optional parameters have a default of None.

--
MOS_MIGRATED_REVID=107957505

1 files changed, 10 insertions, 1 deletions

diff --git a/site/docs/skylark/macros.md b/site/docs/skylark/macros.md
index 9d32c77bee..0a7458c5ef 100644
--- a/site/docs/skylark/macros.md
+++ b/site/docs/skylark/macros.md
@@ -63,7 +63,16 @@ optional (don't give a default value).
 
 * The `name` attribute of rules generated by a macro should include the name
   argument as a prefix. For example, `macro(name = "foo")` can generate a
-  cc_library `foo` and a genrule `foo_gen`.
+  `cc_library` `foo` and a genrule `foo_gen`.
+
+* In most cases, optional parameters should have a default value of `None`.
+  `None` can be passed directly to native rules, which treat it the same as if
+  you had not passing any argument. Thus, there is no need to replace it with
+  `0`, `False`, or `[]` for this purpose. Instead, the macro should defer to the
+  rules it creates, as their defaults may be complex or may change over time.
+  Additionally, a parameter that is explicitly set to its default value looks
+  different than one that is never set (or set to `None`) when accessed through
+  the query language or build-system internals.
 
 * Macros should have an optional `visibility` argument.