This text is easy to miss as it's only at the top, and in the same size
and weight as other intro text. If people follow links to sections (as
is the norm for style guides), this will be completely skipped.
Let's make the notice into a sticky butter bar at the top so it's always
shown regardless of where the person is on the page.
Pull in changes:
* improve Egyptian brackets link
* Add a note about JEP421 to #s6.4-finalizers
* Fix broken link in java-style
* Adding special camel case where word begins with number
* Found an unclosed <span> tag
* Change `<a name` anchors to `<a id` anchors
* Improve inclusive language usage
* Reword title sentence about documenting a warning to better reflect the advice that follows it
* Fix an unclosed <a> tag around sort_java_imports
* Clarify guidance on java vs javatests
PiperOrigin-RevId: 648433358
- Give more explicit guidance about when angle bracket includes should
be used.
- Expand the guidance for disallowing const reference parameters that
outlive the call to *all* references, const or mutable; instead, these
parameters should be pointers.
- Add a brief section about how concepts should be named
There are also additional minor formatting changes or updating
recommendations to prefer std over absl.
- Encourage single line nested namespace declarations.
- Reference and allow `constinit` in the relevant sections
- Update operator overloading guidance for comparison operators: prefer
only to overload `==` and optionally `<=>` when there is an obvious
ordering, and allow the compiler to derive the other comparison
operators.
- Discourage prefixing `uint32_t`, et cetera with `std::`.
- Document when and how to use concepts:
- Use `requires` expressions rather than the alternatives, e.g. a
template parameter.
- Do not reimplement existing concepts/traits.
- Do not expose concepts across API boundaries.
- Do not use concepts unnecessarily.
- Do not implement concepts that are not compile-time checkable.
- Update caveats for `thread_local` usage, particularly around the risk
of destruction order issues.
- Provide explicit guidance for situations where `bit_cast` may be a
better fit than `reinterpret_cast`.
- Emphasize that kConstant-style naming can still be used for `const`
automatic variables that are initialized at runtime, but only if the
resulting variable has the same value with each evaluation (i.e. it
does not depend on runtime inputs).
- Clarify what sorts of details belong in file-level comments vs
comments for individual abstractions.
- Update TODO examples to reflect the preferred styling, from most
preferred to least preferred.
This relaxes the guidance around indenting by 4 additional spaces and provides the Prettier format as one of the examples to ensure the style guide is compatible with the Prettier formatter.
- Encourage use of the `internal` namespace to document parts of an API
that are not public.
- Create a separate section for `switch` statements.
- Require a project-specific prefix for macros.
- Reorganize guidance for formatting conditional statements.
- Other miscellaneous wording and formatting fixes.
pylint triggered:
pylint: Command line or configuration file:1: UserWarning: Specifying exception names in the overgeneral-exceptions option without module name is deprecated and support for it will be removed in pylint 3.0. Use fully qualified name (maybe 'builtins.StandardError' ?) instead.
pylint: Command line or configuration file:1: UserWarning: Specifying exception names in the overgeneral-exceptions option without module name is deprecated and support for it will be removed in pylint 3.0. Use fully qualified name (maybe 'builtins.Exception' ?) instead.
pylint: Command line or configuration file:1: UserWarning: Specifying exception names in the overgeneral-exceptions option without module name is deprecated and support for it will be removed in pylint 3.0. Use fully qualified name (maybe 'builtins.BaseException' ?) instead.
Suggestion works out.
There is no Common Lisp operator named PRINT-UNPRINTABLE-OBJECT. Given the context, it is certain that PRINT-UNREADABLE-OBJECT (www.lispworks.com/documentation/lw51/CLHS/Body/m_pr_unr.htm) was meant instead.
Mike Frysinger