docs: Add using-directive exception for literals
The Google external style guide forbids the usage of using-directives,
regardless of scope. In Pigweed, there are many using-directives for the
purposes of including literal operators, such as std::chrono_literals
and pw::bytes. This CL adds an explicit exception for such uses to the
rule for the Pigweed codebase.
Change-Id: Ia8c002b9646c400463ab578a8ab2988a0ee34a5e
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/96901
Commit-Queue: RJ Ascani <rjascani@google.com>
Reviewed-by: Armando Montanez <amontanez@google.com>
diff --git a/docs/style_guide.rst b/docs/style_guide.rst
index 7a60ba0..67bc4be 100644
--- a/docs/style_guide.rst
+++ b/docs/style_guide.rst
@@ -408,6 +408,28 @@
} // namespace
} // namespace pw::nested
+Using directives for literals
+=============================
+`Using-directives
+<https://en.cppreference.com/w/cpp/language/namespace#Using-directives>`_ (e.g.
+``using namespace ...``) are permitted in implementation files only for the
+purposes of importing literals such as ``std::chrono_literals`` or
+``pw::bytes::unit_literals``. Namespaces that contain any symbols other than
+literals are not permitted in a using-directive. This guidance also has no
+impact on `using-declarations
+<https://en.cppreference.com/w/cpp/language/namespace#Using-declarations>`_
+(e.g. ``using foo::Bar;``).
+
+Rationale: Literals improve code readability, making units clearer at the point
+of definition.
+
+.. code-block:: cpp
+
+ using namespace std::chrono; // Not allowed
+ using namespace std::literals::chrono_literals; // Allowed
+
+ constexpr std::chrono::duration delay = 250ms;
+
Pointers and references
=======================
For pointer and reference types, place the asterisk or ampersand next to the
