Mark Cogan | 6a8e4878 | 2017-08-17 10:06:24 | [diff] [blame] | 1 | ## All files are Objective-C++ |
| 2 | |
| 3 | Chrome back-end code is all C++ and we want to leverage many C++ features, such |
| 4 | as stack-based classes and namespaces. As a result, all front-end Bling files |
| 5 | should be .mm files, as we expect eventually they will contain C++ code or |
| 6 | language features. |
| 7 | |
| 8 | ## Use scoped_nsobject<T> and WeakNSObject<T> where ARC is not available. |
| 9 | |
| 10 | While there are no smart pointers in Objective-C, Chrome has |
| 11 | `scoped_nsobject<T>` and `WeakNSObject<T>` to automatically manage (and |
| 12 | document) object ownership. |
| 13 | |
| 14 | Under ARC,` scoped_nsobject<T>` and `WeakNSObject<T>` should only be used for |
| 15 | interfacing with existing APIs that take these, or for declaring a C++ member |
| 16 | variable in a header. Otherwise use `__weak` variables and `strong`/`weak` |
| 17 | properties. **Note that scoped_nsobject and WeakNSObject provide the same API |
| 18 | under ARC**, i.e. `scoped_nsobject<T> foo([[Bar alloc] init]);` is correct both |
| 19 | under ARC and non-ARC. |
| 20 | |
| 21 | `scoped_nsobject<T>` should be used for all owned member variables in C++ |
| 22 | classes (except the private classes that only exist in implementation files) and |
| 23 | Objective-C classes built without ARC, even if that means writing dedicated |
| 24 | getters and setters to implement `@property` declarations. Same goes for |
| 25 | WeakNSObject - always use it to express weak ownership of an Objective-C object, |
| 26 | unless you are writing ARC code. We'd rather have a little more boilerplate code |
| 27 | than a leak. |
| 28 | |
| 29 | ## Use ObjCCast<T> and ObjcCCastStrict<T> |
| 30 | |
| 31 | As the C++ style guide tells you, we never use C casts and prefer |
| 32 | `static_cast<T>` and `dynamic_cast<T>`. However, for Objective-C casts we have |
| 33 | two specific casts: `base::mac::ObjCCast<T>arg` is similar to `dynamic_cast<T>`, |
| 34 | and `ObjcCCastStrict` `DCHECKs` against that class. |
| 35 | |
| 36 | ## Blocks |
| 37 | |
| 38 | We follow Google style for blocks, except that historically we have used 2-space |
| 39 | indentation for blocks that are parameters, rather than 4. You may continue to |
| 40 | use this style when it is consistent with the surrounding code. |
| 41 | |
| 42 | ## NOTIMPLEMENTED and NOTREACHED logging macros |
| 43 | |
| 44 | `NOTREACHED`: This function should not be called. If it is, we have a problem |
| 45 | somewhere else. |
| 46 | `NOTIMPLEMENTED`: This isn't implemented because we don't use it yet. If it's |
| 47 | called, then we need to figure out what it should do. |
| 48 | |
| 49 | When something is called, but don't need an implementation, just comment that |
| 50 | rather than using a logging macro. |
| 51 | |
| 52 | ## TODO comments |
| 53 | |
| 54 | Sometimes we include TODO comments in code. Generally we follow |
| 55 | [C++ style](https://google.github.io/styleguide/cppguide.html#TODO_Comments), |
| 56 | but here are some more specific practices we've agreed upon as a team: |
| 57 | |
| 58 | * **Every TODO must have a bug** |
| 59 | * Bug should be labeled with **Hotlist-TODO-iOS** |
| 60 | * Always list bug in parentheses following "TODO" |
| 61 | * `// TODO(crbug.com/######): Something that needs doing.` |
| 62 | * Do NOT include http:// |
| 63 | * Optionally include a username for reference |
| 64 | * Optionally include expiration date (make sure it's documented in the bug!) |