Add non-binding recommendations for Target naming conventions to the BUILD style guide.
RELNOTES: None.
PiperOrigin-RevId: 298392631
diff --git a/site/docs/skylark/build-style.md b/site/docs/skylark/build-style.md
index 2a687da..1e4dd1a 100644
--- a/site/docs/skylark/build-style.md
+++ b/site/docs/skylark/build-style.md
@@ -92,8 +92,9 @@
## Target naming
Target names should be descriptive. If a target contains one source file,
-the target should generally be named after that source (e.g., a `cc_library`
-for `chat.cc` should be named "`chat`").
+the target should generally have a name derived from that source (e.g., a
+`cc_library` for `chat.cc` could be named "`chat`", or a `java_library` for
+`DirectMessage.java` could be named "`direct_message`").
The eponymous target for a package (the target with the same name as the
containing directory) should provide the functionality described by the
@@ -104,6 +105,35 @@
instead of `//x:x`). If you are in the same package, prefer the local
reference (`:x` instead of `//x`).
+Avoid using "reserved" target names which have special meaning. This includes
+"`all`", "`__pkg__`", and "`__subpackages__`", these names have special
+semantics and can cause confusion and unexpected behaviors when they are used.
+
+In the absence of a prevailing team convention these are some non-binding
+recommendations that are broadly used at Google:
+
+* In general, use ["snake_case"](https://en.wikipedia.org/wiki/Snake_case)
+ * For a java_library with one src this would mean using a name that is not
+ the same as the filename without the extension
+ * For Java \*\_binary and \*\_test rules use
+ ["Upper CamelCase"](https://en.wikipedia.org/wiki/Camel_case). This
+ allows for the target name to match one of the srcs. For
+ java\_test, this makes it possible for the test\_class attribute to be
+ inferred from the name of the target.
+* If there are multiple variants of a particular target then add a suffix to
+ disambiguate (i.e. :foo_dev, :foo_prod or :bar_x86, :bar_x64)
+* \_test targets should be suffixed with "\_test", "\_unittest", "Test", or
+ "Tests"
+* Avoid meaningless suffixes like "\_lib" or "\_library" (unless necessary to
+ avoid conflicts between a \_library target and its corresponding \_binary)
+* For proto related targets:
+ * proto_library targets should have names ending in "\_proto"
+ * Languages specific \*\_proto_library rules should match the underlying
+ proto but replace "\_proto" with a language specific suffix such as:
+ * cc_proto_library: "\_cc\_proto"
+ * java_proto_library: "\_java\_proto"
+ * java_lite_proto_library: "\_java_proto_lite"
+
## Visibility
Visibility should be scoped as tightly as possible, while still allowing access
