OLD | NEW |
1 # Chromium Objective-C and Objective-C++ style guide | 1 # Chromium Objective-C and Objective-C++ style guide |
2 | 2 |
3 _For other languages, please see the [Chromium style guides](https://chromium.go
oglesource.com/chromium/src/+/master/styleguide/styleguide.md)._ | 3 _For other languages, please see the [Chromium style guides](https://chromium.go
oglesource.com/chromium/src/+/master/styleguide/styleguide.md)._ |
4 | 4 |
5 Chromium follows the | 5 Chromium follows the |
6 [Google Objective-C style guide](https://google.github.io/styleguide/objcguide.x
ml) | 6 [Google Objective-C style guide](https://google.github.io/styleguide/objcguide.x
ml) |
7 unless an exception is listed below. | 7 unless an exception is listed below. |
8 | 8 |
9 A checkout should give you | 9 A checkout should give you |
10 [clang-format](https://chromium.googlesource.com/chromium/src/+/master/docs/clan
g_format.md) | 10 [clang-format](https://chromium.googlesource.com/chromium/src/+/master/docs/clan
g_format.md) |
(...skipping 28 matching lines...) Expand all Loading... |
39 For code in an `@implementation` block, use the Objective-C naming rules. For | 39 For code in an `@implementation` block, use the Objective-C naming rules. For |
40 code in a method of a C++ class, use the C++ naming rules. | 40 code in a method of a C++ class, use the C++ naming rules. |
41 | 41 |
42 For C functions and constants defined in a namespace, use C++ style, even if | 42 For C functions and constants defined in a namespace, use C++ style, even if |
43 most of the file is Objective-C. | 43 most of the file is Objective-C. |
44 | 44 |
45 `TEST` and `TEST_F` macros expand to C++ methods, so even if a unit test is | 45 `TEST` and `TEST_F` macros expand to C++ methods, so even if a unit test is |
46 mostly testing Objective-C objects and methods, the test should be written using | 46 mostly testing Objective-C objects and methods, the test should be written using |
47 C++ style. | 47 C++ style. |
48 | 48 |
| 49 ## All files are Objective-C++ |
| 50 |
| 51 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 sh
ould be .mm files, as we expect eventually they will contain C++ code or languag
e features. |
| 52 ## Use scoped_nsobject<T> and WeakNSObject<T> where ARC is not available. |
| 53 |
| 54 While there are no smart pointers in Objective-C, Chrome has `scoped_nsobject<T>
` and `WeakNSObject<T>` to automatically manage (and document) object ownership.
|
| 55 |
| 56 Under ARC, scoped_nsobject<T> and WeakNSObject<T> should only be used for interf
acing 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. sco
ped_nsobject<T> foo([[Bar alloc] init]); is correct both under ARC and non-ARC. |
| 57 |
| 58 `scoped_nsobject<T>` should be used for all owned member variables in C++ classe
s (except the private classes that only exist in implementation files) and Objec
tive-C classes built without ARC, even if that means writing dedicated getters a
nd setters to implement `@property` declarations. Same goes for WeakNSObject - a
lways 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. |
| 59 |
| 60 This also means that most common uses of `autorelease` (as recommended by the Ob
j-C Style Guide) are no longer necessary. For example, the guide recommends this
pattern for temporary objects: |
| 61 |
| 62 MyObject* temp = [[[MyObject alloc] init] autorelease]; |
| 63 |
| 64 Instead, you can use `scoped_nsobject<T>` to avoid the autorelease and ensure th
e object is cleaned up automatically. |
| 65 |
| 66 scoped_nsobject<MyObject> temp([[MyObject alloc] init]); |
| 67 |
| 68 Obviously, the use of `autorelease` is allowed when the object is the return val
ue or it needs to live beyond the current scope. |
| 69 |
| 70 ## Use ObjCCast<T> and ObjcCCastStrict<T> |
| 71 |
| 72 As C++ style guide tells you, we never use C casts and prefer `static_cast<T>` a
nd `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 `ObjcCCastStri
ct` `DCHECKs` against that class. |
| 73 ## IBOutlets |
| 74 |
| 75 While Apple recommends creating properties for IBOutlets, we discourage that sin
ce 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 propert
y (i.e., declared in the `@interface MyObject ()` block in the implementation fi
le) for that variable. Ensure that you have an `ObjCPropertyReleaser` (see [this
CL](https://chromereviews.googleplex.com/3578024/) for an example) and that wil
l handle releasing the XIB objects. |
| 76 |
| 77 ## Blocks |
| 78 |
| 79 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. |
| 80 |
| 81 ## NOTIMPLEMENTED and NOTREACHED logging macros |
| 82 |
| 83 `NOTREACHED`: This function should not be called. If it is, we have a problem so
mewhere else. |
| 84 `NOTIMPLEMENTED`: This isn't implemented because we don't use it yet. If it's ca
lled, then we need to figure out what it should do. |
| 85 |
| 86 When something is called, but don't need an implementation, just comment that ra
ther than using a logging macro. |
| 87 ## TODO comments |
| 88 |
| 89 Sometimes we include TODO comments in code. Generally we follow [C++ style](http
s://google.github.io/styleguide/cppguide.html#TODO_Comments), but here are some
more specific practices we've agreed upon as a team: |
| 90 * **Every TODO must have a bug** |
| 91 * Bug should be labeled with **Hotlist-TODO-iOS** |
| 92 * Always list bug in parentheses following "TODO" |
| 93 * `// TODO(crbug.com/######): Something that needs doing.` |
| 94 * Do NOT include http:// |
| 95 * Optionally include a username for reference |
| 96 * Optionally include expiration date (make sure it's documented in the bug!) |
| 97 |
OLD | NEW |