Skip to content

Latest commit

 

History

History
91 lines (62 loc) · 3.69 KB

code-conventions.md

File metadata and controls

91 lines (62 loc) · 3.69 KB
Raw

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 for Objective-C code. Note that the Objective-C style guide uses the Google C++ style guide 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 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 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 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.