DEV Community: Mark Truluck

Are you Coding in The Upside Down?

Mark Truluck — Fri, 30 Apr 2021 13:50:20 +0000

In the Netflix show "Stranger Things", some 1980s kids go to an alternate universe they call The Upside Down under the evil control of a horrible creature called the Mind Flayer. In the Upside Down, things sort of look like our universe, but are confusingly different and it is decidedly easy to make a deadly wrong move.

Programming can often feel similar, especially when coming in cold to a new piece of complex software and trying to figure out what is going on. This common situation is made harder by a typical lack of documentation and comments. The standard refrain of "the code is the best documentation" is woefully uncomforting when traipsing through a tangled nest of inexplicable conditional logic.

[Keno Leon]

Like so many things, we know spaghetti code when we see it, but is it possible to characterize bad code in a more objective way? Can you recognize a rhetorical question? Of course you can!

The Leaderboard of Horrors

Although there are many ways to obfuscate the purpose of code, my list for worst offenders are:

Implicit Logical State
State Fragmentation
State Entanglement

What we will see is that these are simply emergent properties of the typical way to code object-oriented classes! So these problems are baked right in to business-as-usual.

As elevators feature prominently in the battles against the Mind Flayer, we will use one as a poster monster for all the ills of coding-as-usual.

Let's investigate these terrors one-by-one.

Implicit Logical State

Everyone knows software has state. Most often the term is discussed with regards to the actual values in the data. For instance, a signed 32 bit integer has a range of [-2147483648 to 2147483647]. That's a lot of possible states!

However we don't often assign logical meaning to each and every distinct value. Instead we chunk up that total range into just a few subranges with meaning, sometimes quite arbitrarily. For instance we might make this map of value => logical state for an elevator simulation:

Values	Logical State
0 to 2147483647	Going Up
-2147483648 to -1	Going Down

(And no, I'm not concerned about boundary conditions. Going to floor 10 gazillion is totally possible on this elevator.)

It's not a very useful elevator yet, but often system design starts with the most common modes of operation and then adding nuance to it.

Let's take a look at a simple skeleton implementation of this elevator (I know you are worried about how to get off the elevator but don't. It's just an example and you can't really get on yet anyway).

In our table above we have two logical states declared. In our code, however, there is no explicit declaration what they are!

There is nothing about (direction >= 0) that just screams this means "Going UP" to the uninformed reader. Instead it's a total superposition of a logical meaning on an arbitrary range of values. This is bad, and as much as you may be saying "I never do this", I'm guessing you've seen it done by somebody else. Am I right?

Additionally, this boolean can be constructed in a number of ways and get the same functional output:

(direction > -1)
!(0 > direction)

etc.

This is the problem of implicit logical state. Code structured to use boolean tests to determine ranges of low level data state that implicitly define logical state are 1) hard to understand and 2) incredibly fragile.

I know you all are thinking of 10 ways to avoid this - and they would all help. But the fact that you have to devise strategies to mitigate a problem that shouldn't exist in the first place is the point of this article. But more to come on the solution later.

Now, we can't always avoid performing conditional tests and, in fact, they aren't inherently "bad" in the first place. However, they are often used badly. And when it relates to determining what our object's internal state is, we can certainly do much better in a lot of cases.

So while you may be able to dodge the worst effects of implicit state by good software engineering practices, not so with the next situation. Let's add some comments and expose the next kind of serious problem this kind of code structure enforces. (There is no escape for you this time).

State Fragmentation

People naturally think in terms of context - where am I, when is it, what is the situation. By understanding context we can then better understand what is happening.

In this example, the two contexts are Going Up and Going Down. However, notice how the code for each of these contexts are fragmented across the event handlers:

I bet you are so used to this that it doesn't strike you as bad, but it really is.

This scattering of a logical state throughout event handlers is one of the most challenging aspects of object-oriented programming languages. And it is bad for you (the developer) for the same reason fragmenting files across a hard drive is bad for your computer:

Your brain has to do the same work as the hard drive - stitch together the parts of a logical "thing" to make complete sense of it. This just isn't how we perceive the world effectively.

Instead, people and hard drives like logically related things kept in the same place. I will assert people in particular (don't know about hard drives) think "contextually" - where am I, what am I doing, what is the situation - and then think about events to decide what to do.

And this gets to the heart of the matter, as all of the programming languages we are most likely using on our projects have no syntax or concept of explicit logical state. Instead, as we have seen, logical state is inferred from low level data.

The solution that I will be proposing fixes this problem.

But first, we must check off the last of the worst offenders - and its a doozy.

State Entanglement

In the Upside Down I don't know why you would, but say we actually wanted to get on our elevator. Then we'd just hack out a new range and shove a Stopped state right in! Easy peasy.

Values	Logical State
1 to 2147483647	Going Up
0	Stopped
-2147483648 to -1	Going Down

Ok so in our specification we have now redefined the logical states the software can be in, but we haven't yet changed our code. So before we do, let's look at how our existing conditional logic maps our newly specified logical state ranges:

Here we can see where the "State Entanglement" problem arises. Our existing rat's nest of boolean logic has already mapped that new logical state right into the existing behavior for Going UP. What to do?

Well, we have to go through ALL our code and disentangle this mess. Let's go step-by-step to see how we get to play "whack-a-mole" with this new state.

First lets fix Going Up and get Stopped out of there:

So this is a partial fix, but it is interesting to get a visual on what would happen if the developer got distracted and checked it in accidentally when invited out to a spaghetti lunch.

Now we have a situation where the stopped state is mapped to be entangled with GoingDown in the first method and GoingUp in the second. If you were to look at this code while the developer was out enjoying meatballs, how would you know that actually both were wrong?

As a final bad situation to explore, here we have all of the methods updated with the proper conditional logic for the existing two states:

However notice that the else clause has "captured" the new Stopped state. Else clauses are a catch-all, and in many situations when a new logical state is added they will accidentally wind up collected there like leaves in a storm drain. It's not a great outcome.

Fixed! Or is it?

Here we can finally see the proper introduction of our Stopped state to the elevator:

While each state is now properly disentangled, we see that the logical states are being torn apart up and down the object-oriented class.

Do you feel your mind being a bit flayed? I'm afraid it is going to get worse before it gets better.

Getting Spagged

This next example doesn't add any new twists to our terrifying tale, but it does help to visually emphasize the Cambrian explosion of fractured logical state metastasizing throughout the codebase:

Eventually it evolves (or devolves?) into a creature you are scared to touch, much less eat:

Flying Spaghetti Monster

Just the kind of thing you might expect to find in the Upside Down.

So what can turn the world right side up? What can save us from going mad from the mind-flaying effects of Implicit Logical State, State Fragmentation and State Entanglement? Glad you asked.

Put Your Code In a Box!

A place for everything and everything in its place - English proverb

There is nothing tidier or less spaghetti like than putting things in boxes. When you put things in boxes (with a good lid of course) they are much less likely to wriggle out and ruin your day.

But how do you choose which box to put something in?

For code, the best answer is an appropriate, small contextual box. We've identified three contexts for our strange elevator:

The "right side up" way to think about what our elevator does is encompassed by being in one of those three contexts, or states. Everything you can do in our elevator maps to being in one of those states.

Happily, computer science provides a theoretical, as well as practical, approach to working with states - the state machine (aka automata).

If this is the best way to organize software, why isn't everyone doing it? The simple answer is that the popular languages programmers use do not make it a natural act to structure code as a state machine. And that is where Frame comes in.

Frame - a Language for State Machines

Frame is a markdown language for specifying state machines, or automata more generally. Frame's additional big benefit is that it can generate code in many object oriented languages (and more to come) as well as documentation.

To tie this all together, here is a demo of our elevator specified in Frame and implemented in JavaScript:

As you can see, the code is structured around the logical states of the system and not around the events that can happen. This inversion of the structure of code immediately makes the purpose of the software evident and it's organization "natural". Developers no longer have to toil in the bizzare realm of the "Upside Down" and can instead frolic in the light with the clarity of context.

Conclusion

To find out more about Frame, have a look at the Frame Website as well as the online version of the Framepiler. The Framepiler is also an open source project that is available under MIT License to use in any way you can imagine. It will lead you to a happier place.

Happy Framing!

State Machines Run Your Life! But don't be scared...

Mark Truluck — Fri, 16 Apr 2021 17:22:09 +0000

[Image: REUTERS/Mario Anzuoni]

State Machine - just the juxtaposition of those two words seems, well, ominous. Is this the totalitarian government of 1984 taking over? Or the Terminator? Or a little of both?

In truth, state machines are already all around you. All software is fundamentally described by them and I really can't do better than this article to explain what they are and why you - assuming you are a developer - should be very interested.

Personally I am very interested in state machines. I believe they are the best way to write intelligible code that aligns to how we, as software creators, actually think about the solutions we are developing.

The problem is, the programming languages we use don't have state as a first class entity. Instead they are, most typically, protected data records with privileged libraries attached - aka "object-oriented programming". If "state" is mentioned at all in these languages, it is described as the summation of the values of the data record being shielded from harm by the outside world by the language semantics.

Another contender is "functional programming" languages. Although theoretically joined at the hip with state machines, their mathematical purity of immutability often obscures the very practical and common purpose of most software - to change things.

So if state machines are omnipresent in software but obscured by the languages we work with, how can we use them in our daily lives as developers?

The Frame System Specification Language

This is exactly the problem I encountered as a young developer in the 90's (ancient history I know) with the advent of the Unified Modeling Language (UML). A key part of the the UML specification was a state machine diagram type (more accurately the Statechart diagram). At first I struggled to understand how to faithfully implement system behavior defined in these model specifications. But, over time, I developed a coding pattern that was easy to understand (at least for me) and repeatable in all of the programming languages I was using.

Eventually I developed a shorthand for expressing this pattern which I now call Frame.

What Is Frame?

I describe Frame as a textual markdown language for system design. The benefits of Frame are:

It turns object-oriented classes into state machines in multiple languages (currently 6)
It creates high-level UML documentation that gives the big picture of what the system does.
It is a simple textual language (you don't have to draw anything)
Its syntax is intentionally terse and symbolic for maximum information density and (hopefully) clarity

So Frame makes it easy to create state machines - great. But why is the really useful? Glad you asked.

What are State Machines good for?

As stated before (yes I said it), state machines compartmentalize code in a way makes it easy to understand what the software is supposed to be doing at any point. This makes building complex software far more intuitive. For instance, when you are thinking about your house, you think about it as a set of joined spaces you traverse in a constrained way.

That is - I can't simply go from the basement den to the upstairs bath. I first have to leave the den, go up the stairs, go down the hall, and then I can enter the bath. This is the very natural kind of structure state machines impose upon the organization of software and makes it much easier to 1) know how many compartments exist and 2) how they relate to each other.

Ok, ok - I know you are now anxious to use state machines in all your upcoming projects. So show me some Frame!

Let there be - Frame.

You're finally old enough so lets shed some light on the subject:

#LampSpec

    -interface-

    toggle

    -machine-

    $Off
        |toggle|
            -> $On ^
    $On
        |>|
            turnOn() ^
        |<|
            turnOff() ^
        |toggle|
            -> $Off ^

    -actions-

    turnOn
    turnOff
##

That is - different.

Yes it is and there is a lot to unpack, but that isn't going to happen in this article. Fortunately, you can find lots of detailed information on Frame syntax at https://frame-lang.org, but for fun right now you can play with a demo of the Frame lamp for hours (press Toggle over and over again):

Here we can see how the UML documentation makes it easy to see the compartments at a glance. As there are only two (well, technically three but whose counting), the utility of the state machine for dealing with complexity is minimal. But as you add more states, and then add other system components that interact with them, the utility becomes highly valuable very quickly.

To see the code behind the demo take a look at it in the Framepiler.

Conclusion

I hope this whirlwind introduction to Frame has intrigued you to learn more. If so please consider joining the State Machines Reddit and/or the Art of the State Discord. I would love to talk Frame with you!