Rewrite visibility advice in build style guide.

Directly from the prior conversation, say both __pkg__ and __subpackages__ are equally appropriate and acceptable. Should I add a section saying to consider __subpackages__ to avoid churn when clients refactor their code?

Re-order so the first thing said is the 'thesis' that "Visibility should be scoped as tightly as possible" (since that seems to be the main takeaway for the section).

From my own experience, directly caution against using package default_visibility.

Note, I am convinced there is a bug regarding default_visibility that is causing too many files to be exposed. Files used as inputs are implicitly exported with default_visibility even if exports_files is never used.

This bug as well as people overusing default_visibility has caused substantial headaches when trying to refactor code.

RELNOTES: Update visibility advice in build-style
PiperOrigin-RevId: 246048587

site/docs/skylark/build-style.md

@@ -117,15 +117,15 @@ reference (`:x` instead of `//x`).
 
 ## Visibility
 
-Do not set the default visibility of a package to `//visibility:public`.
-`//visibility:public` should be individually set for targets in the
-project's public API. These could be libraries which are designed to be
-depended on by external projects or binaries that could be used by an
-external project's build process.
-
-Otherwise, visibility should be scoped as tightly as possible, while still
-allowing access by tests and reverse dependencies. Prefer using `__pkg__` to
-`__subpackages__`.
+Visibility should be scoped as tightly as possible, while still allowing access
+by tests and reverse dependencies. Use `__pkg__` and `__subpackages__` as
+appropriate.
+
+Avoid setting package `default_visibility` to `//visibility:public`.
+`//visibility:public` should be individually set only for targets in the
+project's public API. These could be libraries that are designed to be depended
+on by external projects or binaries that could be used by an external project's
+build process.
 
 ## Dependencies