diff options
Diffstat (limited to 'chromium/styleguide')
-rw-r--r-- | chromium/styleguide/c++/blink-c++.md | 83 | ||||
-rw-r--r-- | chromium/styleguide/c++/c++-dos-and-donts.md | 26 | ||||
-rw-r--r-- | chromium/styleguide/c++/c++.md | 19 | ||||
-rw-r--r-- | chromium/styleguide/c++/c++11.html | 4 | ||||
-rw-r--r-- | chromium/styleguide/java/OWNERS | 1 | ||||
-rw-r--r-- | chromium/styleguide/python/OWNERS | 2 |
6 files changed, 50 insertions, 85 deletions
diff --git a/chromium/styleguide/c++/blink-c++.md b/chromium/styleguide/c++/blink-c++.md index b67e0244b90..31980d8569d 100644 --- a/chromium/styleguide/c++/blink-c++.md +++ b/chromium/styleguide/c++/blink-c++.md @@ -1,29 +1,14 @@ # Blink C++ Style Guide -This document is a list of differences from the overall [Chromium Style Guide], -which is in turn a set of differences from the [Google C++ Style Guide]. The +This document is a list of differences from the overall +[Chromium Style Guide](c++.md), which is in turn a set of differences from the +[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html). The long-term goal is to make both Chromium and Blink style more similar to Google style over time, so this document aims to highlight areas where Blink style -differs from Google style. +differs from Chromium style. [TOC] -## May use mutable reference arguments - -Mutable reference arguments are permitted in Blink, in contrast to Google style. - -> Note: This rule is under [discussion](https://groups.google.com/a/chromium.org/d/msg/blink-dev/O7R4YwyPIHc/mJyEyJs-EAAJ). - -**OK:** -```c++ -// May be passed by mutable reference since |frame| is assumed to be non-null. -FrameLoader::FrameLoader(LocalFrame& frame) - : frame_(&frame), - progress_tracker_(ProgressTracker::Create(frame)) { - // ... -} -``` - ## Prefer WTF types over STL and base types See [Blink readme](../../third_party/blink/renderer/README.md#Type-dependencies) @@ -47,11 +32,11 @@ When interacting with WTF types, use `wtf_size_t` instead of `size_t`. ## Do not use `new` and `delete` -Object lifetime should not be managed using raw `new` and `delete`. Prefer to -allocate objects instead using `std::make_unique`, `base::MakeRefCounted` or -`blink::MakeGarbageCollected`, depending on the type, and manage their lifetime -using appropriate smart pointers and handles (`std::unique_ptr`, `scoped_refptr` -and strong Blink GC references, respectively). See [How Blink Works](https://docs.google.com/document/d/1aitSOucL0VHZa9Z2vbRJSyAIsAz24kX8LFByQ5xQnUg/edit#heading=h.ekwf97my4bgf) +Chromium [recommends avoiding bare new/delete](c++-dos-and-donts.md#use-and-instead-of-bare); +Blink bans them. In addition to the options there, Blink objects may be +allocated using `blink::MakeGarbageCollected` and manage their lifetimes using +strong Blink GC references, depending on the type. See +[How Blink Works](https://docs.google.com/document/d/1aitSOucL0VHZa9Z2vbRJSyAIsAz24kX8LFByQ5xQnUg/edit#heading=h.ekwf97my4bgf) for more information. ## Don't mix Create() factory methods and public constructors in one class. @@ -210,11 +195,13 @@ class RootInlineBox { ``` ### May leave obvious parameter names out of function declarations -[Google C++ Style Guide] allows us to leave parameter names out only if -the parameter is not used. In Blink, you may leave obvious parameter -names out of function declarations for historical reason. A good rule of -thumb is if the parameter type name contains the parameter name (without -trailing numbers or pluralization), then the parameter name isn’t needed. +The +[Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Function_Declarations_and_Definitions) +allows omitting parameter names out when they are unused. In Blink, you may +leave obvious parameter names out of function declarations for historical +reasons. A good rule of thumb is if the parameter type name contains the +parameter name (without trailing numbers or pluralization), then the parameter +name isn’t needed. **Good:** ```c++ @@ -324,45 +311,7 @@ if (frame_->Loader().ShouldClose(false)) { // ... ``` -## Comments -Please follow the standard [Chromium Documentation Guidelines]. In particular, -most classes should have a class-level comment describing the purpose, while -non-trivial code should have comments describing why the code is written the -way it is. Often, what is apparent when the code is written is not so obvious -a year later. - -From [Google C++ Style Guide: Comments]: -> Giving sensible names to types and variables is much better than obscure -> names that must be explained through comments. - ### Use `README.md` to document high-level components Documentation for a related-set of classes and how they interact should be done with a `README.md` file in the root directory of a component. - -### TODO style - -Comments for future work should use `TODO` and have a name or bug attached. - -From [Google C++ Style Guide: TODO Comments]: - -> The person named is not necessarily the person who must fix it. - -**Good:** -```c++ -// TODO(dcheng): Clean up after the Blink rename is done. -// TODO(https://crbug.com/675877): Clean up after the Blink rename is done. -``` - -**Bad:** -```c++ -// FIXME(dcheng): Clean up after the Blink rename is done. -// FIXME: Clean up after the Blink rename is done. -// TODO: Clean up after the Blink rename is done. -``` - -[Chromium Style Guide]: c++.md -[Google C++ Style Guide]: https://google.github.io/styleguide/cppguide.html -[Chromium Documentation Guidelines]: ../../docs/documentation_guidelines.md -[Google C++ Style Guide: Comments]: https://google.github.io/styleguide/cppguide.html#Comments -[Google C++ Style Guide: TODO Comments]:https://google.github.io/styleguide/cppguide.html#TODO_Comments diff --git a/chromium/styleguide/c++/c++-dos-and-donts.md b/chromium/styleguide/c++/c++-dos-and-donts.md index 28e432ee279..e0390201037 100644 --- a/chromium/styleguide/c++/c++-dos-and-donts.md +++ b/chromium/styleguide/c++/c++-dos-and-donts.md @@ -2,8 +2,8 @@ ## A Note About Usage -Unlike the style guide, the content of this page is advisory, not required. You -can always deviate from something on this page, if the relevant +Unlike the [style guide](c++.md), the content of this page is advisory, not +required. You can always deviate from something on this page, if the relevant author/reviewer/OWNERS agree that another course is better. ## Minimize Code in Headers @@ -268,17 +268,25 @@ Good::Good() = default; ## Comment style -The common ways to represent names in comments are as follows: -* Class and type names: `FooClass` -* Function name: `FooFunction()`. The trailing parens disambiguate against - class names, and, occasionally, English words. -* Variable name: `|foo_var|`. Again, the vertical lines disambiguate against - English words, and, occasionally, inlined function names. Code search will - also automatically convert `|foo_var|` into a clickable link. +References to code in comments should be wrapped in `` ` ` `` pairs. Codesearch uses +this as a heuristic for finding C++ symbols in comments and generating +cross-references for that symbol. + +* Class and type names: `` `FooClass` ``. +* Function names: `` `FooFunction()` ``. The trailing parens disambiguate + against class names, and occasionally, English words. +* Variable names: `` `foo_var` ``. Historically, Chrome also used `||` pairs to + delimit variable names; codesearch understands both conventions and will + generate a cross-reference either way. +* Tracking comments for future improvements: `// TODO(crbug.com/12345): ...`, + or, less optimally, `// TODO(knowledgeable_username): ...`. Tracking bugs + provide space to give background context and current status; a username might + at least provide a starting point for asking about an issue. ```cpp // FooImpl implements the FooBase class. // FooFunction() modifies |foo_member_|. +// TODO(crbug.com/1): Rename things to something more descriptive than "foo". ``` ## Named namespaces diff --git a/chromium/styleguide/c++/c++.md b/chromium/styleguide/c++/c++.md index 4d43e6cf079..f13553e8957 100644 --- a/chromium/styleguide/c++/c++.md +++ b/chromium/styleguide/c++/c++.md @@ -1,6 +1,7 @@ # Chromium C++ style guide -_For other languages, please see the [Chromium style guides](https://chromium.googlesource.com/chromium/src/+/master/styleguide/styleguide.md)._ +_For other languages, please see the +[Chromium style guides](https://chromium.googlesource.com/chromium/src/+/master/styleguide/styleguide.md)._ Chromium follows the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) unless an exception @@ -20,11 +21,14 @@ Blink code in `third_party/blink` uses [Blink style](blink-c++.md). ## Modern C++ features -Some features of C++ remain forbidden, even as Chromium adopts newer versions -of the C++ language and standard library. These should be similar to those -allowed in Google style, but may occasionally differ. The status of modern C++ -features in Chromium is tracked in the separate -[C++ use in Chromium](https://chromium-cpp.appspot.com/) page. +Google style +[targets C++17](https://google.github.io/styleguide/cppguide.html#C++_Version). +Chromium targets C++14; [C++17 support](https://crbug.com/752720) is not +expected before +[mid-2021](https://blog.chromium.org/2020/01/moving-forward-from-chrome-apps.html). +Additionally, some features of supported C++ versions remain forbidden. The +status of Chromium's C++ support is covered in more detail in +[Modern C++ use in Chromium](https://chromium-cpp.appspot.com/). ## Naming @@ -34,7 +38,8 @@ features in Chromium is tracked in the separate ## Test-only Code * Functions used only for testing should be restricted to test-only usages - with the testing suffixes supported by [PRESUMBIT.py](https://chromium.googlesource.com/chromium/src/+/master/PRESUBMIT.py). + with the testing suffixes supported by + [PRESUMBIT.py](https://chromium.googlesource.com/chromium/src/+/master/PRESUBMIT.py). `ForTesting` is the conventional suffix although similar patterns, such as `ForTest`, are also accepted. These suffixes are checked at presubmit time to ensure the functions are called only by test files. diff --git a/chromium/styleguide/c++/c++11.html b/chromium/styleguide/c++/c++11.html index cd77ac21d9f..35a7736b2b5 100644 --- a/chromium/styleguide/c++/c++11.html +++ b/chromium/styleguide/c++/c++11.html @@ -18,7 +18,7 @@ table tbody tr td:first-child { </head> <body> <div id="content"> -<h1>C++ use in Chromium</h1> +<h1>Modern C++ use in Chromium</h1> <p><i>This document lives at src/styleguide/c++/c++11.html in a Chromium checkout and is part of the more general @@ -47,7 +47,7 @@ default-allow all non-banned portions of the standard. The current status of existing standards is: <ul><li><b>C++11:</b> <i>Default allowed; see banned features below</i></li> <li><b>C++14:</b> <i>Default allowed; see banned features below</i></li> -<li><b>C++17:</b> <i>Not yet supported in Chromium</i></li> +<li><b>C++17:</b> <i>Not yet supported in Chromium, unlikely before mid-2021; <a href="http://crbug.com/752720">tracking bug</a></i></li> <li><b>C++20:</b> <i>Not yet standardized</i></li></ul></p> <h2>Table of Contents</h2> diff --git a/chromium/styleguide/java/OWNERS b/chromium/styleguide/java/OWNERS index d860494c512..30325ddeb0e 100644 --- a/chromium/styleguide/java/OWNERS +++ b/chromium/styleguide/java/OWNERS @@ -3,4 +3,5 @@ nyquist@chromium.org tedchoc@chromium.org yfriedman@chromium.org +# TEAM: build@chromium.org # COMPONENT: Build diff --git a/chromium/styleguide/python/OWNERS b/chromium/styleguide/python/OWNERS index 6b8b4f6bafe..a9b45078a91 100644 --- a/chromium/styleguide/python/OWNERS +++ b/chromium/styleguide/python/OWNERS @@ -1,5 +1,7 @@ agrieve@chromium.org dpranke@chromium.org +dpranke@google.com wnwen@chromium.org +# TEAM: build@chromium.org # COMPONENT: Build |