summaryrefslogtreecommitdiff
path: root/chromium/styleguide
diff options
context:
space:
mode:
authorAllan Sandfeld Jensen <allan.jensen@qt.io>2020-10-12 14:27:29 +0200
committerAllan Sandfeld Jensen <allan.jensen@qt.io>2020-10-13 09:35:20 +0000
commitc30a6232df03e1efbd9f3b226777b07e087a1122 (patch)
treee992f45784689f373bcc38d1b79a239ebe17ee23 /chromium/styleguide
parent7b5b123ac58f58ffde0f4f6e488bcd09aa4decd3 (diff)
downloadqtwebengine-chromium-c30a6232df03e1efbd9f3b226777b07e087a1122.tar.gz
BASELINE: Update Chromium to 85.0.4183.14085-based
Change-Id: Iaa42f4680837c57725b1344f108c0196741f6057 Reviewed-by: Allan Sandfeld Jensen <allan.jensen@qt.io>
Diffstat (limited to 'chromium/styleguide')
-rw-r--r--chromium/styleguide/c++/blink-c++.md83
-rw-r--r--chromium/styleguide/c++/c++-dos-and-donts.md26
-rw-r--r--chromium/styleguide/c++/c++.md19
-rw-r--r--chromium/styleguide/c++/c++11.html4
-rw-r--r--chromium/styleguide/java/OWNERS1
-rw-r--r--chromium/styleguide/python/OWNERS2
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