mirror of
https://github.com/material-components/material-components-ios.git
synced 2026-02-20 08:27:32 +08:00
fc4e0a4827
Summary: A friendly reminder. Assume you've created MDCFooSpinner which subclasses UIView. - Implement initWithFrame: and initWithCoder: -- Both should call a common method for shared init --- To avoid collisions and problems subclassing, this method should be named commonMDCFooSpinnerInit. Because consistency is the key to all success according to the following book,.... which I have not read, but was high in the Google search results. https://www.amazon.com/Why-Consistency-Key-All-Success/dp/0943845807/ref=sr_1_2?ie=UTF8&qid=1470942356&sr=8-2&keywords=consistency+key+success Test Plan: Works as expected on iPhone Sim 6 - iOS 9. Reviewers: junius, ajsecord, O1 Material components iOS Reviewed By: ajsecord, O1 Material components iOS Tags: #material_components_ios Differential Revision: http://codereview.cc/D1458
92 lines
3.7 KiB
Markdown
92 lines
3.7 KiB
Markdown
# Coding conventions
|
|
|
|
Since we all want to spend more time coding and less time fiddling with whitespace, Material
|
|
Components for iOS uses coding conventions and styles to encourage consistency. Code with a
|
|
consistent coding style is easier (and less error-prone!) to review, maintain, and understand.
|
|
|
|
In general, we try to use established conventions instead of spending engineering time on developing
|
|
new ones; please be patient if MDC's coding style isn't the same as your preferred coding style. :)
|
|
|
|
## Be consistent
|
|
|
|
If you're not sure what to do in any particular situation, the cardinal rule is to **be
|
|
consistent**. For example, take a look at the surrounding code and do whatever it's doing, or look
|
|
for similar classes elsewhere in the code base.
|
|
|
|
## General conventions
|
|
|
|
### Minimize dependencies
|
|
|
|
Avoid non-essential dependencies between components.
|
|
|
|
A goal of MDC is to allow each component to be used independently of the others, as much as
|
|
reasonably possible.
|
|
|
|
- Dependencies increase cost of maintenance and cost of usage for a component, and
|
|
- Dependency-less components are much easier to add and remove from a project.
|
|
- In particular, "Core"- or "Utility"-type components often become a dumping ground and artificially
|
|
increase interdependencies between components.
|
|
|
|
Recommendations:
|
|
|
|
- Aim for zero non-platform dependencies.
|
|
- Create small, targeted components.
|
|
- Watch out for the tendency for components to grow in scope or become overly vague and
|
|
"utility"-like.
|
|
|
|
## Objective-C
|
|
|
|
Objective-C must be used for the implementation of components and can be used for unit tests, UI
|
|
tests, and demonstration apps.
|
|
|
|
### Style
|
|
|
|
Material Components for iOS follows [Google's Objective-C style
|
|
guide](https://google.github.io/styleguide/objcguide.xml) for Objective-C code. Note that the
|
|
Objective-C style guide uses the [Google C++ style
|
|
guide](https://google.github.io/styleguide/cppguide.html) as its "superclass", meaning that rules
|
|
from the C++ style guide are in effect unless the Objective-C style guide indicates otherwise.
|
|
|
|
#### clang-format
|
|
|
|
We use [clang-format](http://clang.llvm.org/docs/ClangFormat.html) to automatically format our
|
|
Objective-C code. If you're going to be contributing more than a few one-offs, we suggest
|
|
[installing clang-format](clang-format.md) to take care of the formatting for you. We recommend
|
|
running clang format on your changes before sending a pull request because it will facilitate
|
|
readability by everyone working on the project.
|
|
|
|
### Nullability annotations
|
|
|
|
Add [nullability annotations](https://developer.apple.com/swift/blog/?id=25) to your public APIs to
|
|
improve Objective-C and Swift interoperations.
|
|
|
|
* Use `_Nullable` and `_Nonnull`, not `__nullable` and `__nonnull`, since the latter are for Xcode
|
|
6.3, which we do not support.
|
|
* Explicitly annotate all public APIs instead of using `NS_ASSUME_NONNULL_BEGIN` and
|
|
`NS_ASSUME_NONNULL_END`.
|
|
|
|
### Macros
|
|
|
|
Avoid macros.
|
|
|
|
* Most uses of macros can be replaced with `static inline` C functions.
|
|
* Macros are appropriate when dealing with system-level macros like
|
|
`__IPHONE_OS_VERSION_MIN_REQUIRED`.
|
|
|
|
### A note about subclassing a UIView
|
|
|
|
Assume you've created MDCFooSpinner which subclasses UIView.
|
|
|
|
* Implement both initWithFrame: and initWithCoder:.
|
|
* If both init methods are setting up the same state, each should call a common method.
|
|
* To avoid collisions and problems subclasses, this common method should be named
|
|
commonMDCFooSpinnerInit.
|
|
|
|
## Swift
|
|
|
|
Swift cannot be used for the implementation of components, but is encouraged for unit tests, UI
|
|
tests, and demonstration apps.
|
|
|
|
Given the rapid change in the Swift language and coding styles, we don't enforce any particular
|
|
style of Swift except to follow the cardinal rule: *be consistent*.
|