Thoughts on consistency and system in naming

[BioPhoton]

Naming inconsistencies the need for a convention/system/matrix

• Start Date: 2019-08-07
• RFC: naming inconsistencies and introduce a system

---

Table of Content

• Summary
• Motivation
• Naming Inconsistencies
• Weakness in the Grouping System
• Suggested methods and tools create a consistent naming system
  • Algebraic Approach
  • Grouping by Functionality
  • Naming with a Matri
• Benefits
• Downsides
• Resume and Goals of this document

---

Summary

This RFC initiates a discussion about the problems of naming in general as well as some ideas for a solution.

Motivation

"Learning operators is very hard because there are many of them."
This is one of the first things people say if you ask them about RxJS. Not only the number of operators makes it hard to learn but also naming inconsistencies and a sometimes weak system in creating operator groups.

A discussion focused to create the big picture on naming and relations as well as grouping should give us an idea of how a consistent naming and grouping could look like.
This serves as the foundation for further discussions on what it would mean if we fixing multiple naming issues in one release and starting from a clean base.

This document will show some:

• examples of the current situation in naming inconsistencies
• examples of the weakness in the current grouping system
• suggestions for methods and tools to introduce a naming system

Naming Inconsistencies

Naming is hard. Also, the fake that this library is pretty old should be considered in this discussion. The goal here is to elaborate on the current situation and show some good examples that should be a small motivation to think for a bigger picture.

In general, I can see a pattern in naming operators, but there are several small or bigger inconsistencies in naming things.

Let me list here some good examples for naming:

• Renaming suggestion for publishLast
• Rename BehaviorSubject to CurrentValueSubject, AsyncSubject to LastValueSubject
• Rename/Alias pairs to entries to provide a more intuitive/JS-aligned API
• Rename/Aliasing the combineAll operator to combineLatestAll
• Rename/Alias the exhaust operator to exhaustAll
• Rename all operators that are duplicates of static operators to xWith variants
• Undeprecate concat operator as concatWith
• observableOf and observableFrom instead of of and from
• Split multicast, publish, et al into static functions and operators?
• window pipeable operator conflict with global window?
• Renaming suggestion for scheduler constants

I guess this shows some good inconsistent naming as well as the fake that there is a need for a system and consistency in naming.

To stress it, even more, I will give some good example of cross relations and complexity in decisions:

• Even if we have not solved the problem of naming conflicts with creation vs operators functions we introduce more operators.

• Let's say we rename of to observableOf, we would also rename al other creation methods. Also the newly introduced scheduled. Also what about the

• Let's say we rename subjects, we would also have to update all related operators to subjects. And here we could end up on what we change in the naming in a pretty long list:

  • Subject related to publish
  • BehaviorSubject related to publishBehavior
  • RelpaySubject related to publishRelpay
  • RelpaySubject related to shareRelpay
  • AsyncSubject related to publishLast

I hope the things above are a good overview of the actual situation and ongoing changes in naming.

Weakness in the Grouping System

Currently, we have the current categories of operators present in the docs like here.

IMHO this information is a bit too hidden for the importance of the information. Grouping/categorization also separation/relation are key for learning to orientate in a big set of data. Very similar to the big set of operators. :)

The actual grouping system has parts that we could improve.

• Creation Operators => type vs functionality
  This group contains a lot of operators that are, from what they do, in the wrong group.
  A good example is the startWith operator is a group of All operators, the endWith operator is missing. Another one is the utility function is a mix of transform operators and other operators that belong to another group. Also i.e. the math section is more intuitive if we include scan
• More subgroups
  For example, the group's filter or transform is very big. They could be subdivided into smaller more meaningful groups
• all concat operators are spread over many different groups => processing vs functionality

Suggested methods and tools create a consistent naming system

In this section, we will discuss different tools and methods we can use to create and validate our naming system. The

• Algebraic Approach
• Grouping by Functionality
• Naming with a Matrix

Algebraic Approach

Algebra means reunion of broken parts. Our operators are, to a major part, consistently named based on reusing parts and combining them with other parts to create new operators.
i.e. switchMapTo => switch, map, to; zipAll => zip, all; mergeScan => merge, scan

Our brain already naturally works with such patterns. We have them in language, nature, tools.
This is I guess the reason why it is so widely implemented in the current naming.

My suggestion here, if somebody wants to find inconsistencies in naming, is to enforce this rule to get the first cheap cleanup.

Grouping by Functionality

This basically means smaller groups focused on the actual meaningful functionality.
So a group can include creation as well as operator functions of all orders (higher-order-operators).

To elaborate on it a little bit I give some suggestions for new groups and their current group:

• scheduling
• combination
• rate-limiting
• side effects
• completion

Another example of grouping by functionality is the multicast group:

The old looks like this:

• multicast
• publish
• publishBehavior
• publishLast
• publishReplay
• share

A group focusing on functionality could look like this:

• multicast (future creation method)
• multicastWith (adopted naming to distinguish from the future multicast operator)
• publish
• publishBehavior
• publishLast
• publishReplay
• share
• shareReplay
• refCount

Naming with a Matrix

Naming based on a matrix is another good technique to get consistency. A very good explanation serves the following issue: 4590

It shows how easy it is to detect problems, gives the consumer a good orientation and the lib maintainer an easy to follow system regarding the naming of future operators and the relations to other operators.

Benefits

If we would have a consistent naming as well as a better grouping we could benefit from several things:

• easier to orientate when learning operators
• a less complex situation when renaming things (reduced cross relations)
• better grouping
• a faster decision in naming new operators
• get a good idea of what operators could potentially exist => missing operators in a naming matrix
• happier consumers

Downsides

• breaking changes
• shit storms :D
• lots of rewrites in the docs
• Invalidation of all "unofficial" content like:
  • blog article
  • tutorial
  • talk
  • screencast
  • podcast
  • website

Resume and Goals of this Document

The main goal of this document was to give an overview of the related topics as well as some tools to create a naming system. Furthermore, it should serve as a place for discussions

---

Update 10.Oct.2019:

As renaming in a delicate topic, I would suggest documenting the current naming system as good as possible, evaluate the upcoming changes against it and reconsider a full evaluation of the current naming system later to see how a possible clean way could look like.

[cartant]

Another downside is the invalidation of already-published, 'unofficial' material. Of which there is ... a lot.

[cartant]

Closing this because:

• publishLast is deprecated.
• I can't see BehaviorSubject being renamed; behavior has a specific FRP meaning.
• pairs is now deprecated in favour of using from(Object.entries(obj))
• of and from have been discussed before and there was no appetite for their being renamed.
• window is being discussed here - but IMO renaming it isn't worth the trouble, as it's so infrequently used, it's not a problem in Node - only in the browser - and it's trivial to alias it with where it's imported.
• IDK that there is much to be gained from renaming the schedulers with all-caps names. Really, EMPTY is what it is because it had to co-exist with a deprecated empty. I think we should just live with the names as they are now.

And all of the other suggestions have now been implemented. 🎉