The file uses UTF-8 encoding, so use UTF-8 directly instead of HTML
entities. This is handled by the export/publish code, but seemed a
bit nicer to split this out into a separate commit for review.
Internally, we've turned down the JS styleguide in favor of a merged
TS/JS guide (with heavy emphasis on TS). That variant doesn't exist
publicly yet, and even then, we probably want to keep around the JS
version as-is more or less indefinitely like we have with the older
ES5 guide. Once we update the TS guide, we can add a deprecation
notice to this file like we do with the ES5 guide.
There is one change that has been left out: the heavy emphasis on
only using clang-format as the rules are heavily geared towards
google3, and there is no external guidance for formatting. If we
could provide public guidance here, it'd be great to update, but
since the guide is no more internally, that seems unlikely, so it's
probably best to freeze the pre-clang-format guidance here.
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.
Sidney San Martín