How to write clean Arduino code: introducing the Eloquent library

Eloquent Arduino is an attempt to bring sanity and clarity in Arduino projects. The purpose of this library is to create a wide range of constructs to clearly translate your ideas into meaningful code: stop writing spaghetti code only you can undestand, please! I'll show you how.

The problem

Arduino sells itself as a platform well suited for beginners, and it is for sure; lots of non-tech people are able to bring their ideas to life thanks to this awesome platform.
Nevertheless, I often stumble upon bits of code over the internet that make me question about the quality of the projects people are producing.

Even the Arduino official website is misleading in this sense, in my opinion, since it promotes a code style really straighforward, but suited for toy projects, with little logics and low complexity level.

Here's an example of what I'm talking about, copy-pasted from the Arduino official site (with comments removed):

const int ledPin =  LED_BUILTIN;
int ledState = LOW;
unsigned long previousMillis = 0; 
const long interval = 1000; 

void setup() {
  pinMode(ledPin, OUTPUT);
}

void loop() {
  unsigned long currentMillis = millis();

  if (currentMillis - previousMillis >= interval) {
    previousMillis = currentMillis;

    if (ledState == LOW) {
      ledState = HIGH;
    } else {
      ledState = LOW;
    }

    digitalWrite(ledPin, ledState);
  }
}

Can you tell what this code does with a minimum mental effort?
I don't think so (you may have recognized the async pattern and it actually blinks a LED in a non-blocking fashion).

THIS is the problem: most Arduino code is not clear at first glance, is not eloquent. By eloquent I mean code that speaks by itself, without the need for comments.

The solution

What about the following?

DigitalOut led(LED_BUILTIN);

void setup() {
    led.begin();
}

void loop() {
    every(1 Second) {
        led.toggle();
    }
}

I swear this is valid code that compiles just fine. Hopefully, it does the exact same thing as above, yet it is far more readable and understandable.

Can you see my point now? Wouldn't it be much easier and reliable to code with the help of a set of such eloquent constructs / interfaces? I strongly believe it is, and this is why I'm writing this library.
Asynchronous programming, pin state managements, animations are bits of code that pop up over and over again in most of the projects, yet every time we start from zero and write the same boilerplate code over and over again.

Boilerplate code heavily relies on a fixed structure that could be hard to adapt to your specific case. Longer code means more chances to break something and more code to debug, which can waste lots of your valuable time.

I'm starting a series of posts where I'll document some of the classes and constructs the library provides to you. You can find the code on the Github repo.