Our component development principals.

Maxx Greene — Thu, 28 Jan 2021 18:18:33 +0000

Building a component library it’s not an easy task, notably when it fulfills the purpose of being used by multiple projects and requirements are continually changing. Given these challenges, we have a set of principles that guide us through the process of creating reliable components.‌

API design is foundational: We take this field seriously.

Don’t start writing any code until the specification document is done and evaluated by the team.
Design from restricted API then relax based on valid use cases.
Create a deterministic API that doesn’t allow you to do the same thing in two different ways.
Defer it as long as possible. The best way of reducing the impact of breaking changes is to avoid them in the first place.

Until you have the information necessary, you are just guessing at what is needed and your success is determined largely by luck. I also believe you may be grossly underestimating the costs of speculation. — WayneMack
Generalization process is the key to avoid breaking changes. Avoid generalizing your component too early but keep in mind that the new API shouldn’t compromise generalize when new use cases arrive. I wrote more about this interesting topic here.

First-class Testing: Our components are test infected. There isn’t software improvement without refactoring and there isn’t refactoring without tests.

Internationalization: We design each component with i18n in mind. Any new component or feature has to be able to work fully in different locales.

react-rainbow-components wouldn’t be possible without the support of engineers from around the world. Thus, building a component library with internationalization is a requirement, not a nice to have.

Accessibility: It’s part of our definition of done. It’s a must-have for each component.

Documentation: It’s critical to the success of any project. There is no adoption without good documentation.

I know you have your own set of principles, let us know if ours make sense to you, we are eager to learn from you. Comment below.

Generalization Process applied to API design of UI components.

Maxx Greene — Thu, 28 Jan 2021 18:05:31 +0000

To make a piece of machinery “more general” you have to modify it to be capable of doing something other than what it already does, while making sure it can still do what it does now.

What is Generation Process?

If you search on Google about “Generation Process” one of the first results returned — at least for my Google profile :) — would be the Wikipedia definition.

Basically, the definition describes that given two related concepts A and B, A is a “generalization” of B (equivalent, B is a special case of A) if and only if both of the following hold:

Every instance of concept B is also an instance of concept A.
There are instances of concept A which are not instances of concept B.

The concept might have a more specific meaning in a specialized context(e.g. generalization in learning, generalization in programming).

Generalization in programming

In my early days doing programming with Delphi and later with Java everything was about Object-Oriented Programming(OOP). Back then we read Object-oriented analysis and design with applications and Generalization was tight in our mental model to Inheritance.

The concept of Animal is a generalization of the concept of Dog since every dog is an animal but not every animal is a dog(a cat, for instance).

Here some other examples of Generalization in programming:

Abstract Classes. Abstract classes isolate the common characteristics of their descendants.
Templates. Templates allow functions and classes to be parameterized by type.
Libraries. Placing a piece of code in a library allows it to be used by more than one program.

How we applied it to UI components API design?

A UI component implementation by itself is a Generalization of all the use cases that support when you build it to be reusable in more than one use case or in more than one application. But how is Generation related to API design?

When designing a component API you should defer implementing features as long as possible to avoid making guesses.

Until you have the information necessary, you are just guessing at what is needed and your success is determined largely by luck. I also believe you may be grossly underestimating the costs of speculation. WayneMack.

At some point, you can’t defer anymore a new feature for a component, it’s clear that this feature belongs to component A, then one of the first question to ask ourself is, how the new version of the API won’t compromise the previous use cases.

In other words, if every use case of your component is a special case of your component API, the new API must not conflict with the previous use cases or that will be considered a breaking change or a violation of the generalization process.

Conclusion

There isn't a single receipt for always apply the generalization process on API design. I always try to exercise generalization with the future API of the component by asking: how the new API won’t compromise other use cases we might want to implement in the future?