diff options
Diffstat (limited to 'chromium/styleguide')
| -rw-r--r-- | chromium/styleguide/c++/c++11.html | 330 | ||||
| -rw-r--r-- | chromium/styleguide/objective-c/objective-c.md | 49 | ||||
| -rw-r--r-- | chromium/styleguide/web/OWNERS | 1 |
3 files changed, 316 insertions, 64 deletions
diff --git a/chromium/styleguide/c++/c++11.html b/chromium/styleguide/c++/c++11.html index 4fe82713de4..861a1f3ef6a 100644 --- a/chromium/styleguide/c++/c++11.html +++ b/chromium/styleguide/c++/c++11.html @@ -7,7 +7,7 @@ found in the LICENSE file. <html> <head> <meta charset="utf-8"> -<title>C++11 use in Chromium</title> +<title>C++11 and C++14 use in Chromium</title> <link rel="stylesheet" href="c++11.css"> <style> table tbody tr td:first-child { @@ -18,18 +18,19 @@ table tbody tr td:first-child { </head> <body> <div id="content"> -<h1>C++11 use in Chromium</h1> +<h1>C++11 and C++14 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 <a href="https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/c++.md"> Chromium C++ style guide</a>.</i></p> -<p>This summarizes the new and updated features in C++11 (for both the language -itself and the Standard Library) from the perspective of what's allowed in -Chromium. When applicable, it contains pointers to more detailed information. -This Guide applies to Chromium and its subprojects, though subprojects can -choose to be more restrictive if necessary for toolchain support.</p> +<p>This summarizes the new and updated features in C++11 and C++14 (for both +the language itself and the Standard Library) from the perspective of what's +allowed in Chromium. When applicable, it contains pointers to more detailed +information. This Guide applies to Chromium and its subprojects, though +subprojects can choose to be more restrictive if necessary for toolchain +support.</p> <p>You can propose changing the status of a feature by sending an email to <a href="https://groups.google.com/a/chromium.org/forum/#!forum/cxx"> @@ -41,16 +42,34 @@ change this file accordingly, linking to your discussion thread.</p> <h2>Table of Contents</h2> <ol class="toc"> <li>Allowed Features<ol> - <li><a href="#core-whitelist">Language</a></li> - <li><a href="#library-whitelist">Library</a></li> + <li>Language + <a href="#core-whitelist">C++11</a> + <a href="#core-whitelist-14">C++14</a> + </li> + <li>Library + <a href="#library-whitelist">C++11</a> + <a href="#library-whitelist-14">C++14</a> + </li> </ol></li> <li>Banned Features<ol> - <li><a href="#core-blacklist">Language</a></li> - <li><a href="#library-blacklist">Library</a></li> + <li>Language + <a href="#core-blacklist">C++11</a> + <a href="#core-blacklist-14">C++14</a> + </li> + <li>Library + <a href="#library-blacklist">C++11</a> + <a href="#library-blacklist-14">C++14</a> + </li> </ol></li> <li>To Be Discussed<ol> - <li><a href="#core-review">Language</a></li> - <li><a href="#library-review">Library</a></li> + <li>Language + <a href="#core-review">C++11</a> + <a href="#core-review-14">C++14</a> + </li> + <li>Library + <a href="#library-review">C++11</a> + <a href="#library-review-14">C++14</a> + </li> </ol></li> </ol> @@ -334,6 +353,27 @@ template <typename T><br/>void Function(T&& t) { ... }</code></td> </tbody> </table> +<h2 id="whitelist"><a name="core-whitelist-14"></a>C++14 Allowed Features</h2> + +<p>Nothing yet. Suggest something!</p> +<!--<p>The following features are currently allowed.</p>--> + +<!-- +<table id="whitelist_lang_list_14" class="unlined striped"> +<tbody> + +<tr> +<th style='width:220px;'>Feature</th> +<th style='width:260px;'>Snippet</th> +<th style='width:240px;'>Description</th> +<th style='width:240px;'>Documentation Link</th> +<th style='width:240px;'>Notes and Discussion Thread</th> +</tr> + +</tbody> +</table> +--> + <h2 id="whitelist"><a name="library-whitelist"></a>C++11 Allowed Library Features</h2> <p>The following library features are currently allowed.</p> @@ -548,7 +588,49 @@ template <typename T><br/>void Function(T&& t) { ... }</code></td> </tbody> </table> -<h2 id="blacklist">C++11 Blacklist (Disallowed and Banned Features)</h2> +<h2 id="whitelist"><a name="library-whitelist-14"></a>C++14 Allowed Library Features</h2> + +<p>The following library features are currently allowed.</p> + +<table id="whitelist_lib_list" class="unlined striped"> +<tbody> + +<tr> +<th style='width:240px;'>Feature or Library</th> +<th style='width:240px;'>Snippet</th> +<th style='width:240px;'>Description</th> +<th style='width:240px;'>Documentation Link</th> +<th style='width:240px;'>Notes and Discussion Thread</th> +</tr> + +<tr> +<td><code>std::integer_sequence</code></td> +<td><code>template <size_t... I><br>void CallFooImpl(std::index_sequence<I...>) {<br> Foo(I...);<br>}<br><br>template <size_t N><br>void CallFoo() {<br> CallFooImpl(std::make_index_sequence<N>());<br>}</code></td> +<td>Template metaprogramming utility for representing a sequence of integers as a type.</td> +<td><a href="http://en.cppreference.com/w/cpp/utility/integer_sequence">std::integer_sequence</a></td> +<td>This also includes the alias, <code>std::index_sequence</code>, which is the specialization for <code>size_t</code>. <a href="https://groups.google.com/a/chromium.org/d/msg/cxx/ow7hmdDm4yw/EDEvBRi_BQAJ">Discussion thread</a></td> +</tr> + +<tr> +<td><code>std::make_unique</code></td> +<td><code>auto widget = std::make_unique<Widget>();</code></td> +<td>Allocates objects on the heap and immediately constructs an <code>std::unique_ptr</code> to assume ownership.</td> +<td><a href="http://en.cppreference.com/w/cpp/memory/unique_ptr/make_unique">std::make_unique</a></td> +<td>Should replace <code>base::MakeUnique</code> and <code>WTF::MakeUnique</code>. <a href="https://groups.google.com/a/chromium.org/d/msg/cxx/ow7hmdDm4yw/EDEvBRi_BQAJ">Discussion thread</a></td> +</tr> + +<tr> +<td>Transparent function objects</td> +<td>Arithmetic operations:<br><code>std::plus<>, std::minus<></code> ...<br>Comparisons:<br><code>std::less<>, std::equal_to<></code>...<br>Logical operations:<br><code>std::logical_and<>, std::logical_or<></code>...<br>Bitwise operations:<br><code>std::bit_and<>, std::bit_or<></code>...<br></td> +<td>Function objects that deduce argument types.</td> +<td><a href="http://en.cppreference.com/w/cpp/utility/functional/less_void">std::less<></a></td> +<td>Should replace <code>base::less</code> and usage of these functors with explicit types where appropriate. Note: std::set/std::map do not yet support transparent comparators on all platforms <a href="https://crbug.com/756020">bug</a>. <a href="https://groups.google.com/a/chromium.org/forum/#!topic/cxx/cPoULd2NY9k">Discussion thread</a></td> +</tr> + +</tbody> +</table> + +<h2 id="blacklist">C++11 and C++14 Blacklist (Disallowed and Banned Features)</h2> <p>This section lists features that are not allowed to be used yet. @@ -607,9 +689,41 @@ std::move(t).f(); // second</code></td> <td>Banned in the <a href="https://google.github.io/styleguide/cppguide.html#Operator_Overloading">Google Style Guide</a>.</td> </tr> +<tr> +<td>thread_local storage class</td> +<td><code>thread_local int foo = 1;</code></td> +<td>Puts variables into thread local storage.</td> +<td><a href="http://en.cppreference.com/w/cpp/language/storage_duration">Storage duration</a></td> +<td>Some surprising effects on Mac (<a href="https://groups.google.com/a/chromium.org/forum/#!topic/chromium-dev/2msN8k3Xzgs">discussion</a>, <a href="https://groups.google.com/a/chromium.org/forum/#!topic/cxx/h7O5BdtWCZw">fork</a>). Use <a href="https://cs.chromium.org/chromium/src/base/threading/sequence_local_storage_slot.h">SequenceLocalStorageSlot</a> for sequence support, and <a href="https://cs.chromium.org/chromium/src/base/threading/thread_local.h">ThreadLocal</a>/<a href="https://cs.chromium.org/chromium/src/base/threading/thread_local_storage.h">ThreadLocalStorage</a> otherwise.</td> +</tr> + </tbody> </table> +<h3 id="blacklist_banned"><a name="core-blacklist-14"></a>C++14 Banned Features</h3> + +<p>Nothing yet. Suggest something!</p> + +<!-- +<p>This section lists C++14 features that are not allowed in the Chromium +codebase. +</p> + +<table id="banned_list" class="unlined striped"> +<tbody> + +<tr> +<th style='width:240px;'>Feature or Library</th> +<th style='width:240px;'>Snippet</th> +<th style='width:240px;'>Description</th> +<th style='width:240px;'>Documentation Link</th> +<th style='width:240px;'>Notes and Discussion Thread</th> +</tr> + +</tbody> +</table> +--> + <h3 id="blacklist_stdlib"><a name="library-blacklist"></a>C++11 Banned Library Features</h3> <p>This section lists C++11 library features that are not allowed in the Chromium codebase.</p> @@ -708,6 +822,31 @@ std::move(t).f(); // second</code></td> </tbody> </table> +<h3 id="blacklist_stdlib"><a name="library-blacklist-14"></a>C++14 Banned Library Features</h3> + +<p>This section lists C++14 library features that are not allowed in the Chromium codebase.</p> + +<table id="blacklist_lib_list" class="unlined striped"> +<tbody> + +<tr> +<th style='width:240px;'>Feature</th> +<th style='width:240px;'>Snippet</th> +<th style='width:240px;'>Description</th> +<th style='width:240px;'>Documentation Link</th> +<th style='width:240px;'>Notes and Discussion Thread</th> +</tr> + +<tr> +<td><code>std::chrono</code> literals</td> +<td><code>using namespace std::chrono_literals;<br>auto timeout = 30s;</code></td> +<td>Allows <code>std::chrono</code> types to be more easily constructed.</td> +<td><a href="http://en.cppreference.com/w/cpp/chrono/operator%22%22s">std::literals::chrono_literals::operator""s</a></td> +<td>Banned because <code><chrono></code> is banned.</td> +</tr> + +</tbody> +</table> <h3 id="blacklist_review"><a name="core-review"></a>C++11 Features To Be Discussed</h3> @@ -751,6 +890,109 @@ std::move(t).f(); // second</code></td> </tbody> </table> +<h3 id="blacklist_review"><a name="core-review-14"></a>C++14 Features To Be Discussed</h3> + +<p>The following C++14 language features are currently disallowed. See the top of this page on how to propose moving a feature from this list into the allowed or banned sections.</p> + +<table id="blacklist_review_list" class="unlined striped"> +<tbody> + +<tr> +<th style='width:240px;'>Feature</th> +<th style='width:240px;'>Snippet</th> +<th style='width:240px;'>Description</th> +<th style='width:240px;'>Documentation Link</th> +<th style='width:240px;'>Notes and Discussion Thread</th> +</tr> + +<tr> +<td><code>[[deprecated]]</code> attribute</td> +<td><code>[[deprecated]] void f();<br> +[[deprecated("use h() instead")]] void g();</code></td> +<td>Marks a function as deprecated.</td> +<td><a href="http://en.cppreference.com/w/cpp/language/attributes">Standard attributes</a></td> +<td>We don't use deprecation warnings in Chromium; if you want to deprecate +something, remove all callers and remove the function instead.</td> +</tr> + +<tr> +<td>Aggregate member initialization</td> +<td><code>struct Point { int x, y, z = 0; };<br>Point p = {2, 3};</code></td> +<td>Allows classes with default member initializers to be initialized with aggregate initialization, optionally omitting data members with such initializers.</td> +<td><a href="http://en.cppreference.com/w/cpp/language/aggregate_initialization">aggregate initialization</a></td> +<td></td> +</tr> + +<tr> +<td>Binary literals</td> +<td><code>int i = 0b1001;</code></td> +<td>Allows defining literals in base two.</td> +<td><a href="http://en.cppreference.com/w/cpp/language/integer_literal">Integer literals</a></td> +<td>Might confuse syntax highlighting in editors. No standard library support +for printing or reading in this format. Still seems useful in minor ways.</td> +</tr> + +<tr> +<td><code>decltype(auto)</code> variable declarations</td> +<td><code>decltype(auto) x = 42;</code></td> +<td>Allows deducing the type of a variable using <code>decltype</code> rules.</td> +<td><a href="http://en.cppreference.com/w/cpp/language/auto">auto specifier</a></td> +<td>Often more surprising than <code>auto</code>. For instance, the <code>decltype</code> deduction rules do not remove references.</td> +</tr> + +<tr> +<td>Function return type deduction</td> +<td><code>auto f() { return 42; }<br>decltype(auto) g() { return 42; }</code></td> +<td>Allows the return type of a function to be automatically deduced from its return statements, according to either template or <code>decltype</code> rules.</td> +<td><a href="http://en.cppreference.com/w/cpp/language/function#Return_type_deduction">Return type deduction</a></td> +<td>Likely to be primarily useful in abstract template code.</td> +</tr> + +<tr> +<td>Generic lambdas</td> +<td><code>[](const auto& x) { <i>...</i> }</code></td> +<td>Allows lambda argument types to be deduced using <code>auto</code> (according to the rules that apply to templates).</td> +<td><a href="http://en.cppreference.com/w/cpp/language/lambda">lambda expressions</a></td> +<td></td> +</tr> + +<tr> +<td>Lambda capture expressions</td> +<td><code>auto widget = base::MakeUnique<Widget>();<br>auto lambda = [widget = std::move(widget)]() {<br> SetWidget(std::move(widget));<br>}</code></td> +<td>Allows lambda captures to be explicitly initialized with expressions.</td> +<td><a href="http://en.cppreference.com/w/cpp/language/lambda#Lambda_capture">Lambda capture</a></td> +<td>Particularly useful to capture move-only types in a lambda when a reference would go out of scope. Less useful without allowing lambdas to outlive the scope.</td> +</tr> + +<tr> +<td>Number literal separators</td> +<td><code>float f = 1'000'000.000'1;</code></td> +<td><code>'</code>s anywhere in int or float literals are ignored</td> +<td><a href="http://en.cppreference.com/w/cpp/language/integer_literal">Integer literals</a>, <a href="http://en.cppreference.com/w/cpp/language/floating_literal">Floating point literals</a></td> +<td>Might confuse syntax highlighting in editors. No standard library support +for printing or reading in this format. Seems less useful and harder on editors +than binary literals.</td> +</tr> + +<tr> +<td>Relaxed constant expressions</td> +<td><code>constexpr int Factorial(int n) {<br> int result = 1;<br> while (n > 0)<br> result *= n--;<br> return result;<br>}</code></td> +<td>Allows use of more declarations, conditional statements and loops inside <code>constexpr</code> functions.</td> +<td><a href="http://en.cppreference.com/w/cpp/language/constexpr">constexpr specifier</a></td> +<td>Likely to get used even without approval, since the C++11 rules were not trivial to remember.</td> +</tr> + +<tr> +<td>Variable templates</td> +<td><code>template <typename T><br>constexpr T tau = T(6.283185307179586476925286766559);</code></td> +<td>Allows templates that declare variables, rather than functions or classes.</td> +<td><a href="http://en.cppreference.com/w/cpp/language/variable_template">Variable template</a></td> +<td></td> +</tr> + +</tbody> +</table> + <h3 id="blacklist_stdlib_review"><a name="library-review"></a>C++11 Standard Library Features To Be Discussed</h3> <p>The following C++ library features are currently disallowed. See the top of this page on how to propose moving a feature from this list into the allowed or banned sections.</p> @@ -930,6 +1172,66 @@ std::move(t).f(); // second</code></td> </tbody> </table> +<h3 id="blacklist_stdlib_review"><a name="library-review-14"></a>C++14 Standard Library Features To Be Discussed</h3> + +<p>The following C++14 library features are currently disallowed. See the top of this page on how to propose moving a feature from this list into the allowed or banned sections.</p> + +<table id="banned_stdlib" class="unlined striped"> + +<tbody> +<tr> +<th style='width:240px;'>Feature</th> +<th style='width:240px;'>Snippet</th> +<th style='width:240px;'>Description</th> +<th style='width:240px;'>Documentation Link</th> +<th style='width:240px;'>Notes</th> +</tr> + +<tr> +<td>Constant begin/end non-member functions</td> +<td><code>std::cbegin(<i>container</i>)<br>std::cend(<i>container</i>)<br>std::crbegin(<i>container</i>)<br>std::crend(<i>container</i>)</br></code></td> +<td>Constant counterparts to <code>std::begin</code> etc.</td> +<td><a href="http://en.cppreference.com/w/cpp/iterator/begin">std::cbegin</a></td> +<td></td> +</tr> + +<tr> +<td>Heterogeneous lookup in associative containers</td> +<td><code><i>// Does not construct an std::string to use as the lookup key.</i><br>std::map<std::string, int, std::less<>> map;<br>auto it = map.find("answer");</code></td> +<td>Allows searching associative containers without converting the key to exactly match the stored key type, assuming a suitable comparator exists.</td> +<td><a href="http://en.cppreference.com/w/cpp/utility/functional/less">std::less</a></td> +<td></td> +</tr> + +<tr> +<td><code>std::complex</code> literals</td> +<td><code>using namespace std::complex_literals;<br>std::complex<double> c = 2.0 + 0.5i;</code></td> +<td>Allows <code>std::complex</code> objects to be more easily constructed.</td> +<td><a href="http://en.cppreference.com/w/cpp/numeric/complex/operator%22%22i">std::literals::complex_literals</a></td> +<td></td> +</tr> + +<td><code>std::string</code> literals</td> +<td><code> +#include <string><br> +using std::literals::string_literals::operator"" s;<br> +auto s = "asdf"s; // deduces to std::string</code></td> +<td>Allows literals of type <code>std::string</code></td> +<td><a href="http://en.cppreference.com/w/cpp/string/basic_string/operator%22%22s">std::literals::string_literals::operator""s</a></td> +<td></td> +</tr> + +<tr> +<td>Tuple addressing by type</td> +<td><code>std::tuple<int, char> enterprise(1701, 'D');<br>int n = std::get<int>(enterprise);</code></td> +<td>Allows entries in a tuple to be accessed by type rather than entry, if it is not ambiguous.</td> +<td><a href="http://en.cppreference.com/w/cpp/utility/tuple/get">std::get(std::tuple)</a></td> +<td></td> +</tr> + +</tbody> +</table> + </div> </body> </html> diff --git a/chromium/styleguide/objective-c/objective-c.md b/chromium/styleguide/objective-c/objective-c.md index 5cd5379053c..e37bb76ef05 100644 --- a/chromium/styleguide/objective-c/objective-c.md +++ b/chromium/styleguide/objective-c/objective-c.md @@ -46,52 +46,3 @@ most of the file is Objective-C. mostly testing Objective-C objects and methods, the test should be written using C++ style. -## All files are Objective-C++ - -Chrome back-end code is all C++ and we want to leverage many C++ features, such as stack-based classes and namespaces. As a result, all front-end Bling files should be .mm files, as we expect eventually they will contain C++ code or language features. -## Use scoped_nsobject<T> and WeakNSObject<T> where ARC is not available. - -While there are no smart pointers in Objective-C, Chrome has `scoped_nsobject<T>` and `WeakNSObject<T>` to automatically manage (and document) object ownership. - -Under ARC, scoped_nsobject<T> and WeakNSObject<T> should only be used for interfacing with existing APIs that take these, or for declaring a C++ member variable in a header. Otherwise use __weak variables and strong/weak properties. **Note that scoped_nsobject and WeakNSObject provide the same API under ARC**, i.e. scoped_nsobject<T> foo([[Bar alloc] init]); is correct both under ARC and non-ARC. - -`scoped_nsobject<T>` should be used for all owned member variables in C++ classes (except the private classes that only exist in implementation files) and Objective-C classes built without ARC, even if that means writing dedicated getters and setters to implement `@property` declarations. Same goes for WeakNSObject - always use it to express weak ownership of an Objective-C object, unless you are writing ARC code. We'd rather have a little more boilerplate code than a leak. - -This also means that most common uses of `autorelease` (as recommended by the Obj-C Style Guide) are no longer necessary. For example, the guide recommends this pattern for temporary objects: - - MyObject* temp = [[[MyObject alloc] init] autorelease]; - -Instead, you can use `scoped_nsobject<T>` to avoid the autorelease and ensure the object is cleaned up automatically. - - scoped_nsobject<MyObject> temp([[MyObject alloc] init]); - -Obviously, the use of `autorelease` is allowed when the object is the return value or it needs to live beyond the current scope. - -## Use ObjCCast<T> and ObjcCCastStrict<T> - -As C++ style guide tells you, we never use C casts and prefer `static_cast<T>` and `dynamic_cast<T>`. However, for Objective-C casts we have two specific casts: `base::mac::ObjCCast<T>arg` is similar to `dynamic_cast<T>`, and `ObjcCCastStrict` `DCHECKs` against that class. -## IBOutlets - -While Apple recommends creating properties for IBOutlets, we discourage that since it makes the details of the view hierarchy public. Instead, declare a private variable, mark that as the IBOutlet, and then create a private retained property (i.e., declared in the `@interface MyObject ()` block in the implementation file) for that variable. Ensure that you have an `ObjCPropertyReleaser` (see [this CL](https://chromereviews.googleplex.com/3578024/) for an example) and that will handle releasing the XIB objects. - -## Blocks - -We follow Google style for blocks, except that historically we have used 2-space indentation for blocks that are parameters, rather than 4. You may continue to use this style when it is consistent with the surrounding code. - -## NOTIMPLEMENTED and NOTREACHED logging macros - -`NOTREACHED`: This function should not be called. If it is, we have a problem somewhere else. -`NOTIMPLEMENTED`: This isn't implemented because we don't use it yet. If it's called, then we need to figure out what it should do. - -When something is called, but don't need an implementation, just comment that rather than using a logging macro. -## TODO comments - -Sometimes we include TODO comments in code. Generally we follow [C++ style](https://google.github.io/styleguide/cppguide.html#TODO_Comments), but here are some more specific practices we've agreed upon as a team: -* **Every TODO must have a bug** -* Bug should be labeled with **Hotlist-TODO-iOS** -* Always list bug in parentheses following "TODO" - * `// TODO(crbug.com/######): Something that needs doing.` - * Do NOT include http:// -* Optionally include a username for reference -* Optionally include expiration date (make sure it's documented in the bug!) - diff --git a/chromium/styleguide/web/OWNERS b/chromium/styleguide/web/OWNERS index 6aad1e89052..d7e4f49972e 100644 --- a/chromium/styleguide/web/OWNERS +++ b/chromium/styleguide/web/OWNERS @@ -1,4 +1,3 @@ # Interested in helping maintain this? Let us know! -dbeam@chromium.org dpapad@chromium.org michaelpg@chromium.org |