Reactivecocoa: RAC5 and Swift 3 API Guidelines

[andersio]

Since the Swift 3 API Guidelines is _mostly_ settled, I wonder if we should consider aligning the 5.0 API to the community's newborn convention.

We can treat our operators as terms of art, so that things like map from the reactive programming domain needn't be renamed. But at least shall we follow the rules of argument labels and type/variable/assertion naming rules?

P.S. Also updating the documentation in source code to use Xcode markup?

[mdiep]

But at least shall we follow the rules of argument labels and type/variable/assertion naming rules?

👍

P.S. Also updating the documentation in source code to use Xcode markup?

Want to open a separate issue for that?

[cloutiertyler]

I've been adding Swift 3 compatibility to a few libraries over the past weeks. The syntax changes are pretty significant considering that the default behavior for the first parameter of functions has changed. It's likely you'll have to change many function declarations just to get it to compile, so it makes sense to evaluate conformance to the new guidelines as you go.

Any thoughts on adding a SwiftPM package? I would be very interested investigating and helping out with that.

[andersio]

Hmm... it seems we might have clashes like observe(on: myScheduler) after the renaming.

[mdiep]

I don't think observe(on: myScheduler) is an appropriate name because it's not observing the events—it's just changing where they're observed.

We could probably just stick with observeOn for now. Maybe observed(on: scheduler) would work? on(scheduler) could work too, but that overlaps with the current on(). Or we could go back to deliver(on:).

[andersio]

@mdiep That sounds a nice option, and we may need a renaming for startOn too.

Though I wonder if there is a legitimate reason to have two producer operators instead of a single one that enforces the start handler & event delivery on a particular scheduler.

[RiuHDuo]

@mdiep i think observeOn(scheduler: SchedulerType) should be renamed to start(on scheduler: SchedulerType)

[mdiep]

I'm definitely 👎 on start(on scheduler: SchedulerType). That makes it sound like it's actually starting the producer. And we have an existing startOn operator.

Let's just stick with observeOn and startOn for now.

[RiuHDuo]

@mdiep i saw many function in swift 3, such as Data.write(to url: URL, options: WritingOptions),tableView.deselectRow(at indexPath: IndexPath, animated: Bool) and so on.
May be observeOn(scheduler: SchedulerType) 's function name change to the word start will sound like starting something. But i wish the word on should be an argument label not be a part of function name.
you can call it observe(on scheduler: SchedulerType) delivery(on scheduler: SchedulerType) or something else

[JaviSoto]

I wonder if it should be observing(on), since it returns a copy and doesn't modify the callee. That way observe can be preserved.
I haven't read the entire guidelines yet, but this is my understanding.

[andersio]

@JaviSoto If we follow the guidelines strictly:

Those without side-effects should read as noun phrases, e.g. x.distance(to: y), i.successor().

Those with side-effects should read as imperative verb phrases, e.g., print(x), x.sort(), x.append(y).

Name Mutating/nonmutating method pairs consistently.

A mutating method will often have a nonmutating variant with similar semantics, but that returns a new value rather than updating an instance in-place.

When the operation is naturally described by a verb, use the verb’s imperative for the mutating method and apply the “ed” or “ing” suffix to name its nonmutating counterpart.

All the RAC operators can be said as non-mutating, given that the signal, the producer or the property being acted upon is not mutated.

So... are we going to suffix all the operators? Are we going to follow closely on the conventions and naming of Swift and the stdlib, instead of being familiar for those from ReactiveObjC or Rx?

TL;DR: The name clashing between observing(on: ) and the family of observing(observer:) still exists if we are all in.

---

Note that on swift-evolution, there is an on-going thread on (finally) complying the core functional methods to these rules. There is also a proposal (https://github.com/apple/swift/pull/2981) on departing from names originated from FP.

So the guidelines turn out to be not _quite_ settled yet... Perhaps I opened this issue too early. 🙈

[liscio]

So... are we going to suffix all the operators? Are we going to follow closely on the conventions and naming of Swift and the stdlib, instead of being familiar for those from ReactiveObjC or Rx?

I would be strongly in favour of following the Swift conventions. That's effectively what RAC is about—being a model citizen on the host platform rather than following Rx/etc.

As for concerns about people familiar with RACObjC, those same people need to "wrap their head around" naming changes in Foundation and AppKit when transitioning to Swift already so it's not as big a deal, IMO.

I am not at all grossed out by started(on: SchedulerType) and observing(on: SchedulerType) if we can't come up with something that seems more obvious once we find it. 😄

[mdiep]

TL;DR: The name clashing between observing(on: ) and the family of observing(observer:) still exists if we are all in.

I don't think that's true. I believe observe(observer:) would be appropriate since it has side-effects.

Also, I think ed is preferable to ing where possible per the stdlib conventions.

So we'd have observed(on:) and observe(observer:), which is quite palatable to me.

I would be strongly in favour of following the Swift conventions. That's effectively what RAC is about—being a model citizen on the host platform rather than following Rx/etc.

Let's have this fight after the stdlib settles on something. ☺️

[NachoSoto]

I would vote for not changing the suffix on the operators. My reasoning is that RAC types are immutable, so since there's no way for an operator to actually mutate the signal it's called on, there is no reason to make that unambiguous.

[andersio]

Since we read codes more than we write, and we can not always instantly know the instance being acted upon is a let constant or not, the guidelines - in my understanding - argues that it would help explicitly communicate the intention of mutability by consistently having -ed or -ing suffixes.

But so far core FP methods are exempted from these rules, and swift-evolution is battling discussing this, alongside the naming of Sequence that may affect our choices of names.

[andersio]

Swift 3.0 have been frozen for any further proposals. 🎉

A wrap-up of what API renames have been made in Swift 3.0 that might affect us, AFAICT:

1. -ing and -ed suffixes for all non-mutating instance methods..
2. Core Functional Operators are so far kept intact as terms of art (e.g. map, flatMap), except for flatten being renamed to joined in the last minute.
3. "Rationalizing Sequence Operators" hasn't made it. However, it is still up for future releases.

I think we may at least rename our APIs with the non-mutating rule, except for core FP operators, flatten, observe (kind of mutating) and start (factory + term of art). Then we may figure out the consistency and suitability of our choices of names, e.g. #2990.

We need not follow how Sequence might end up though, since it is rationalising a data structure, while we are modelling discrete-time signals.

[mdiep]

I think I'm 👎🏻 on adding suffixes in general. But this is definitely something to consider on a case-by-case basis.

[mdiep]

Closing this because we've migrated our APIs. We can consider future changes in future issues/PRs.