2018-12-18 RAC-Best practices

Best practices

https://github.com/ReactiveCocoa/ReactiveObjC/blob/master/Documentation/DesignGuidelines.md#best-practices

RAC-based code predictable, understandable, and performant.

Use descriptive declarations for methods and properties that return a signal

    There are three key questions that can inform a declaration:

        1:Is the signal hot (already activated by the time it's returned to the caller) or cold         (activated when subscribed to)?

        2:Will the signal include zero, one, or more values?

        3:Does the signal have side effects?

    Hot signals without side effects should typically be properties instead of methods

    Cold signals without side effects should be returned from methods that have noun-like names (e.g., -currentText).

    Signals with side effects should be returned from methods that have verb-like names (e.g., -logIn). 

Indent stream operations consistently

1 2

Use the same type for all the values of a stream

    RACStream (and, by extension, RACSignal and RACSequence) allows streams to be composed of heterogenous objects, just like Cocoa collections do.

    Whenever possible, streams should only contain objects of the same type.

Avoid retaining streams for too long

    Retaining any RACStream longer than it's needed will cause any dependencies to be retained as well, potentially keeping memory usage much higher than it would be otherwise.

    A RACSequence should be retained only for as long as the head of the sequence is needed. If the head will no longer be used, retain the tail of the node instead of the node itself.

Process only as much of a stream as needed

    As well as consuming additional memory, unnecessarily keeping a stream or RACSignal subscription alive can result in increased CPU usage, as unnecessary work is performed for results that will never be used.

    If only a certain number of values are needed from a stream, the -take: operator can be used to retrieve only that many values, and then automatically terminate the stream immediately thereafter.

    Operators like -take: and -takeUntil: automatically propagate cancellation up the stack as well. If nothing else needs the rest of the values, any dependencies will be terminated too, potentially saving a significant amount of work.

Deliver signal events onto a known scheduler

    When a signal is returned from a method, or combined with such a signal, it can be difficult to know which thread events will be delivered upon. Although events are guaranteed to be serial, sometimes stronger guarantees are needed, like when performing UI updates (which must occur on the main thread).

    Whenever such a guarantee is important, the -deliverOn: operator should be used to force a signal's events to arrive on a specific RACScheduler.

Switch schedulers in as few places as possible

    Switching schedulers can introduce unnecessary delays and cause an increase in CPU load.

    Generally, the use of -deliverOn: should be restricted to the end of a signal chain – e.g., before subscription, or before the values are bound to a property.

Make the side effects of a signal explicit

    As much as possible, RACSignal side effects should be avoided, because subscribers may find the behavior of side effectsunexpected

    However, because Cocoa is predominantly imperative, it is sometimes useful to perform side effects when signal events occur.

    Although most RACStream and RACSignal operators accept arbitrary blocks (which can contain side effects), the use of -doNext:, -doError:, and -doCompleted: will make side effects more explicit and self-documenting:

1

Share the side effects of a signal by multicasting

    Side effects occur for each subscription by default, but there are certain situations where side effects should only occur once – for example, a network request typically should not be repeated when a new subscriber is added.

    The -publish and -multicast: operators of RACSignal allow a single subscription to be shared to any number of subscribers by using a RACMulticastConnection:

1

Debug streams by giving them names

   1: Every RACStream has a name property to assist with debugging.

Avoid explicit subscriptions and disposal

    There are almost always higher-level patterns that can be used instead of manual subscriptions and disposal:

    The RAC() or RACChannelTo() macros can be used to bind a signal to a property, instead of performing manual updates when changes occur.

    Operators like -takeUntil: can be used to automatically dispose of a subscription when an event occurs (like a "Cancel" button being pressed in the UI).

Avoid using subjects when possible

    Subjects are a powerful tool for bridging imperative code into the world of signals, but, as the "mutable variables" of RAC, they can quickly lead to complexity when overused.

    Since they can be manipulated from anywhere, at any time, subjects often break the linear flow of stream processing and make logic much harder to follow

Subjects can usually be replaced with other patterns from ReactiveCocoa:

    1:Instead of feeding initial values into a subject, consider generating the values in a +createSignal: block instead.

    2:Instead of delivering intermediate results to a subject, try combining the output of multiple signals with operators like+combineLatest: or +zip:.

    3:Instead of using subjects to share results with multiple subscribers, multicast a base signal instead.

4:Instead of implementing an action method which simply controls a subject, use a command or -rac_signalForSelector:instead.

Implementing new operators

1:Implementing a new operator requires a careful attention to detail and a focus on simplicity, to avoid introducing bugs into the calling code.

Prefer building on RACStream methods

1:RACStream offers a simpler interface than RACSequence and RACSignal, and all stream operators are automatically applicable to sequences and signals as well.

2:new operators should be implemented using only RACStream methods whenever possible. The minimal required methods of the class, including -bind:, -zipWith:, and -concat:, are quite powerful, and many tasks can be accomplished without needing anything else.

3:If a new RACSignal operator needs to handle error and completed events, consider using the -materialize method to bring the events into the stream.

4:All of the events of a materialized signal can be manipulated by stream operators, which helps minimize the use of non-stream operators.

Compose existing operators when possible

1：To minimize duplication and possible bugs, use the provided operators as much as possible in a custom operator implementation.

2: Generally, there should be very little code written from scratch.

Avoid introducing concurrency

1：Concurrency is an extremely common source of bugs in programming. 

2:To minimize the potential for deadlocks and race conditions, operators should not concurrently perform their work.

3:Callers always have the ability to subscribe or deliver events on a specific RACScheduler, and RAC offers powerful ways to parallelize work without making operators unnecessarily complex.

Cancel work and clean up all resources in a disposable

1:When implementing a signal with the +createSignal: method, the provided block is expected to return a RACDisposable. This disposable should:

    1:As soon as it is convenient, gracefully cancel any in-progress work that was started by the signal.

    2:Immediately dispose of any subscriptions to other signals, thus triggering their cancellation and cleanup code as well.

    3:Release any memory or other resources that were allocated by the signal.

2:This helps fulfill the RACSignal contract.

Do not block in an operator

1:Stream operators should return a new stream more-or-less immediately

2:Any work that the operator needs to perform should be part of evaluating the new stream, not part of the operator invocation itself.

1

Avoid stack overflow from deep recursion

1:Any operator that might recurse indefinitely should use the -scheduleRecursiveBlock: method of RACScheduler.

2:This method will transform recursion into iteration instead, preventing a stack overflow.

3:For example, this would be an incorrect implementation of -repeat, due to its potential to overflow the call stack and cause a crash:

1

By contrast, this version will avoid a stack overflow: