summaryrefslogtreecommitdiff
path: root/chromium/styleguide/c++/c++-dos-and-donts.md
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/c++/c++-dos-and-donts.md
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/c++/c++-dos-and-donts.md')
-rw-r--r--chromium/styleguide/c++/c++-dos-and-donts.md26
1 files changed, 17 insertions, 9 deletions
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