DEV Community: Mikhail Palei

The Ultimate Goal of Programming

Mikhail Palei — Sun, 03 Dec 2023 18:56:33 +0000

Is to have code that is easy to change.
This is a simple statement, and perhaps it will not even provoke a large number of disputes. Because it is obvious that it is useful to have code that is easy to change. Even if you do not agree that this is the ultimate goal of programming, you probably still agree with the usefulness of the concept as a whole.

Let's break it down. What problem are we trying to solve?
I think this is a fundamental problem for programmers. The thing is, we do not understand, or have false ideas about, why we are programming at all.

For example, when welders weld a structure at a construction site, they know that this structure is needed in order to build a house. They use welding because it is very important for the house to be strong. To prevent the house from collapsing. To prevent people from dying in a collapse. This is vital.

Perhaps this seems too obvious. Perhaps it sounds as if I am describing the fact that water is wet and the sky is blue. But ask yourself: what do programmers think about when writing code? What is the ultimate goal of their activity?
“To make a product” is the answer I received in the vast majority of cases.

The problem is that the very concept of a "product" is constantly changing. Have you ever heard the saying: "In programming, there is only one constant: everything always changes." Just as no business plan survived first contact with the consumer, all projects always change in the course of development. New requirements emerge. Bugs and errors force us to refine and revise.

This is why "making a product" is an extremely wrong way to look at programming. This approach implies that there is a clear plan. That everything is written down and planned so that the plans do not fail or change. That there are requirements that will not change. That there will be no mistakes or bugs.

This vision also does not imply that the concept of a "product" is not only vague and constantly changing, but also constantly expanding. New features and use cases appear for the application, new services emerge. The business will always try to retain current users by expanding functionality and improving the service. Or simply change and adapt to new markets.

I do not want to confuse you with these arguments. The idea here is very simple: there is no such thing as a "finished product" in programming. Our work is never finished. We can support the current product for a long time, we may be reassigned to another or we may simply be fired. For example, because the money ran out. But the situation where the product is built and finished happens extremely rarely. There are probably exceptions to this rule, but I ask you to note that these are precisely exceptions that confirm the rule.

What do I want to say and where am I leading with this?

I’ll draw an example from practice. Because it will help you put this knowledge into practice.

Recently, I was involved in training a new employee. He was given a task:
• the mobile application has a list. The list displays only one item. The remaining list items are hidden.
• If you press "show full list", then the entire list will be displayed instead of just one item. For example, 10 items.
• A change is required. It is necessary for three items to be displayed at the very beginning, rather than just one. Meaning, when you enter the page, you see three items in the list, you press the "show full list" button, and then 10 items are displayed.

The developer approached this issue the same way as many might: he wrote the code so that the list could take an argument. Meaning, you can tell the list how many items should be in the list before the button is pressed. His reasoning was simple: "I want to ensure that I won't have any problems with this list in the future. If I ever need to use this list somewhere else, or use several lists with different initial numbers of elements, I just need to specify the right argument. There will never be any more issues with this element." In this way, he was making it "future proof."

This is absolutely logical. It makes sense. And it is obviously useful.

However, when the developer asked me about my opinion on this solution, it surprisingly made me think. In programming, there are many different principles. There is one that is rarely applied and often even provokes disputes: KISS (Keep It Simple Stupid).

In order to display just one item, we previously had the following line:

list.sublist(0, 1)

To display any number of items, we planned to use this line:

list.sublist(0, amountOfInitialItemsToDisplay)

At first glance, the change seems not critical. But upon closer examination, it turned out that the complexity of our code sharply increased. If previously we had only one test that had a very simple description "if the button is not pressed, make sure that only one item is displayed," now we need several tests:
• "if the button is not pressed and if it is indicated to display only one initial item, make sure that only one item is displayed"
• "if the button is not pressed and if it is indicated to display 3 items, then make sure that three items are displayed"
• "if the button is not pressed and if nothing is indicated to display (the argument is missing), then display the default value—three items"
• "if the button is not pressed and if it is indicated to display 0 items, make sure that 0 items are displayed"
• "if the button is not pressed and if a negative number is given, throw an error"
• "if the button is not pressed and if a number is given that exceeds the number of list items, throw an error"

Perhaps the last few tests may seem excessive to you, and these situations are made up. Indeed, I agree with you, this is so. But the key idea is that previously we did not have such potential situations, such problems, and so many tests. And now, due to a small change in logic, our code has become more complex. We have more code and tests that need to be maintained, and it has become more difficult to understand all of this.

On the other hand, we have considerations that we really can change the list in the future (if we change it now, who said we won't change it in the future?), the list may have a different appearance on different pages, and indeed, it doesn't feel future proof.

So what should we choose?

At that moment, I asked myself: what is the ultimate goal of programming? The ultimate goal of programming is to have code that is easy to change. If we look at the problem from this point of view, the answer becomes obvious.

We need to change this:

list.sublist(0, 1)

To this:

list.sublist(0, 3)
Then update one test, and the work is done.

This is a way to add the least amount of complexity.

This is a way through which, if we were asked to change this list in any way, we would have the fewest problems.

Judge for yourself: if we had a dynamic number of elements, there would be more logic, more checks, more tests, and more code in general.
So when it is necessary to change this list (and this moment will definitely come, because it is an axiom), this greater complexity would hinder us. We would have to take it into account, write new tests and checks. It turns out that complexity leads to even greater complexity, and it can even multiply in geometric progression.

Ultimately, despite the fact that these considerations are very logical, they still seemed to me to be somehow wrong. As if unlawful. Did I spend all my time learning different principles and gaining experience just to change one number to another in the end? What about SOLID? What about DRY? Maybe use some programming pattern? Maybe extract the logic of creating the list? Maybe create two classes instead of one? Maybe through inheritance somehow? Maybe something else?

In my specific example, everything is very simple, and it may seem like these considerations are far-fetched. But if we abstract from the specifics of my example, it becomes clear that this is often how we think. We have our own knowledge, experience, ideas, and concerns. And very soon, if you dig deeper, it becomes clear that we make decisions based on a multitude of factors. Someone writes code so as not to worry about the future. Someone likes to use proven techniques. Someone just wants to close the task as quickly as possible. Someone just doesn't know what they're doing.

And none of these decisions are made from a position of common sense. Because the most sensible thing we can do every day is to write code so that it is easy to change. Because as programmers, we spend the lion's share of our time somehow changing our code.

In conclusion, I would like to say that in my opinion, all the principles and best practices that we apply actually come down to the idea written at the beginning of the article.

DRY == do not duplicate code, write so that changes do not have to be made in many places instead of one.

Architecture == correctly divide the project into layers, so that changes in one layer do not affect others == write code so that it is easy to change.

SOLID == write code so that when adding functionality, we add classes, not change existing ones == write classes so that it is easy to make changes to the project.

Clean code == write code so that it is easy to read and understand what it does. So that it is easy to make changes.

And so on.

Therefore, every time I ask myself questions about how to solve a problem in code, I just ask myself, "What is the ultimate goal of programming?" And then come up with a way through which the code will be easiest to change in the future. I recommend the same to you.

Should class names really be nouns? Rethinking the classics

Mikhail Palei — Tue, 27 Dec 2022 11:35:18 +0000

The problem

One of the most fundamental ways of thinking in terms of Object Oriented Programming is thinking in objects. Does this look familiar?

class Dog {
    bark();

    waveTail();
}

Sadly, in programming we rarely actually use nouns. We usually operate via verbs.

For example, Repository names should not be written via nouns. Next code example is written via nouns and it breaks SOLID principles:

class ChatsRepository {
    getChat();

    getChats();

    updateChat();

    deleteChat();
}

Here is the fixed version. This code does not break SOLID:

class ChatGetterRepository {
    getChat();
}

class ChatsGetterRepository {
    getChats();
}

class ChatUpdaterRepository {
    updateChat();
}

class ChatDeleterRepository {
    deleteChat();
}

But this code is still far from being perfect. Can you name the problem with it?

Programmers usually spend 90% of their time actually reading the code not writing it (source: Clean Code by Robert C. Martin). Thus the easier it is to read the code the less time you will spend on adding features and fixing bugs.

Now we come to an important question: what code is easy to read and what is hard to read? Well, interesting thing about reading is the fact that we internally pronounce code while we read it. And if code is easy to pronounce then it is easy to read (source: also Clean Code by Robert C. Martin).

Try to read out loud these 2 class names: ChatDeleter and DeleteChat. Obviously, second one is easier on the tongue. The first one is too clunky. Cha-t-de-le-te-r vs De-le-te-cha-t.

On top of that it is important to use words that we actually use in real life. Because the code should not be cryptic. The code is written for humans to understand not for the machines. The machines do not care if we name our class x, y, ChatDeleter, or MegaUltraZoomZoomChatDeleterAgentRepositoryClass9000. We write code programmers. For our fellow humans. For our selfs. So why on earth do we name our classes so alien and cryptic? Why do we write things like ChatDeleter instead of DeleteChat? Have ever tried to describe your code to your teammate?

-Hey, team mate! What are you working on? What do you want to do?

Compare these answers:

-Hey! I want to use chat repository to delete a chat.
-Hey! I want to use chat deleter to delete a chat.
-Hey! I want to delete a chat.

I think it goes without saying that first two answers are just plain weird. Yet these is exactly how we write code. We simply have been doing it for so long that we don’t even see the problem anymore.

The solution

The solution is quite simple: we need to use verbs instead of nouns for naming our classes.

Here are our new classes:

class GetChatRepository {
    getChat();
}

class GetChatsRepository {
    getChats();
}

class UpdateChatRepository {
    updateChat();
}

class DeleteChatRepository {
    deleteChat();
}

// Example usage:
DeleteChatRepository().deleteChat();

Some languages even allow us to avoid code duplication by using conventions. Java has main() method, Dart has call() and Go has… well, go().

class GetChatRepository {
    call();
}

class GetChatsRepository {
    call();
}

class UpdateChatRepository {
    call();
}

class DeleteChatRepository {
    call();
}
// Example usage:
DeleteChatRepository().call();
// Dart allows us to have a shortcut:
DeleteChatRepository()();

If you are still not convinced that nouns are the way to go let me demonstrate a typical code that uses Dependency Injection:

// Example of DI using nouns.
class ChatDeleter {
    // Next two lines represent the way Dependency injection usually works in Dart.
    final ChatDeleterRepository chatDeleterRepo;
    const DeleteChatUseCase({required this.chatDeleterRepo});

    deleteChat() {
        chatDeleterRepo.deleteChat();
    }
}

ChatDeleterUseCase().deleteChat();

// Example of DI using verbs.
class DeleteChat {
    // Next two lines represent the way Dependency injection usually works in Dart.
    final DeleteChatRepository deleteChat;
    const DeleteChatUseCase({required this.deleteChat});

    call() {
        deleteChat();
    }
}

DeleteChat()();

Why it is important

If code is not written in plain english and you need to do any kind of mental transformation or guess work then it is not readable code. It is a structured mess.

The sad thing is classes are the most fundamental thing we use. This means that we constantly mentally jump through hoops by doing guess work, mental transformation and internally pronouncing unreadable words. It is an invisible perpetual torture.

How to use build context outside of Flutter widgets

Mikhail Palei — Fri, 16 Dec 2022 16:00:28 +0000

Short answer:

If you need to use BuildContext outside of Flutter widgets use the package created based on ideas of this article:

https://pub.dev/packages/build_context_provider

Long answer:

When I started working with Flutter one of the most confusing things for me were inability to use methods that required BuildContext outside of flutter widgets.

Lets say you want to have a reusable class that navigates to a certain page of the app. You might want to use that class without a "context" argument. For example, in Clean Architecture use cases must never rely on any framework or library specific code. Since BuildContext is specific to Flutter framework this code is invalid in Clean Architecture:

class NavigateToProfileUseCase {
  call(BuildContext context) {
    Navigator.of(context).pushNamed('/profile');
  }
}

What is the solution?

Note: the explanation of the solution is going to sound somewhat confusing. Please bear with me. It is going to get clearer by the end of the article.

In order to fix this problem we must change the way we call these functions. Instead calling functions directly we must pass these functions to the special widget that is going to run in UI layer.

Here is what we must do:

We must create a special class which is going to hold a function. Let’s call it a Publisher. This can be a Cubit/Bloc, a Stream or a ChangeNotifier or any other reactive class.
We must create a special widget that is going to listen to the changes of the Publisher.
This widget must invoke functions pushed to the Publisher with the latest BuildContext instance.

Let’s take a look at an example:

class NavigateToProfileUseCase {
    call() { // <- notice how we don't pass BuildContext anymore
        functionRunnerCubit.runFunction(
        (context) => Navigator.of(context).pushNamed('/profiile'),
      );
    }
}

final functionRunnerCubit = FunctionRunnerCubit();

class FunctionRunnerCubit extends Cubit<FunctionRunnerState> {
  FunctionRunnerCubit() : super(FunctionRunnerWithNoFunctionsToRun());

  void runFunction(Function(BuildContext context) VoidCallback functionToRun) => emit(
        FunctionRunnerWithFunctionToRun({function: functionToRun}),
      );
}

class FunctionRunner extends StatelessWidget {
  const FunctionRunner({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return BlocListener<FunctionRunnerCubit, ContextListenerState>(
        listener: (buildContext, state) {
          if (state is FunctionRunnerWithFunctionToRun) {
            state.callback(buildContext);
          }
        },
        child: SizedBox(),
    );
  }
}

Explanation of the code:

Inside of the UseCase we pass a function that we want to run with a BuildContext to the Cubit.

The Cubit publishes this function to the listeners.

FunctionRunner widget listens to the changes of the Cubit.

The BlocListener(think of it simply as a Listener if you don’t know the “bloc” library) invokes the function with a latest instance of the BuildContext.

In conclusion

This simple combination of a Publisher and a Listener will allow you to run your Flutter specific code anywhere. Such freedom will allow you to write simpler, cleaner and more maintainable code.

Mixing state and logic is an anti-pattern

Mikhail Palei — Sun, 11 Dec 2022 16:15:41 +0000

The art of programming is, at its core, the art of managing data. Take the Facebook app, for example: there are user posts, direct messages, friends lists, friend requests, and more. But does it really matter what the "Send" button in a chat looks like? Does it matter whether you scroll posts vertically or horizontally? Or whether the notification indicator is on the left or the right?

On one hand, details like these do matter. On the other hand, it's easy to see that they're just surface-level concerns. If we strip all of them away, what remains is the essence of any application: data, and how we manage it.

For example, when you send a message to a friend, two things happen:

A network request is sent to an API to save the message in a database.
The message appears at the bottom of the chat screen.

In both steps, we're simply taking data and doing something with it—sending it or showing it. That's what programming boils down to: managing data.

So how does state management relate to this? Well, "state management" literally means "managing the state of data"—or just data management. These two terms are essentially interchangeable.

But most developers never make this connection. When people hear "state management," they often think of business logic, or a "glue" layer that connects the UI and the logic. Because of this, state management is often treated as an afterthought. Why care about the "glue" if it doesn't seem important?

But if we replace the term "state management" with "data management," its importance becomes obvious. You can't afford to treat your data as an afterthought. It's the foundation of your application.

Building applications is hard—especially when multiple teams and hundreds of thousands of lines of code are involved. In my opinion, one of the biggest reasons it's so difficult is that nobody handles data management properly. And as I've said, data management is the most fundamental part of software engineering.

So, why was this article written? In my 10 years of programming, I've never seen a team, a developer, or even a single article that gets state management right.

Today, we're going to talk about the most fundamental mistake in state management: unpredictable states—a problem that arises when logic and state are mixed together.

What is the problem?

To understand the problem, let me explain with an example. Let's say we're building a chat application. The app has chat rooms, and each chat room has a list of messages. When a chat room is opened, we need to download the latest messages and display them to the user.

Here's how state management is usually done in this case:

When a user lands on the page, some kind of state method is called:
chatRoomState.getLatestMessages();

Inside this method, there is typically a use case or a controller:

class ChatRoomState {
  getLatestMessages() async {
    final downloadedMessages = await GetChatRoomMessagesUseCase.call();
    // Set the new state and notify all listeners.
    state.latestMessages = downloadedMessages;
  }
}

Inside the use case, we usually call a repository:

class GetChatRoomMessagesUseCase {
  call() async {
    return await getChatRoomMessagesRepository.call();
  }
}

class GetChatRoomMessagesRepository {
  call() async {
    return await http.get('/chat-room/123/messages');
  }
}

Here's a diagram of that process:

Note: if you're unfamiliar with use cases or repositories, think of them simply as classes that perform specific actions. In this example, state methods call classes, which in turn call other classes. There's a clear nesting of responsibilities.

So, what's the problem?

Let's say we're asked to show a "Messages loaded successfully" snackbar after the messages are downloaded. Whether or not it's good UX is not our call—we just need to implement it.

Now the question is: where should this code go?

Putting the snackbar inside the ChatRoomState doesn't feel right—snackbars and chat room data shouldn't be mixed. Adding it to the repository is definitely wrong, since repositories should only handle one responsibility. So maybe we should place it in the use case?

That sounds reasonable at first:

class GetChatRoomMessagesUseCase {
  call() async {
    final messages = await getChatRoomMessagesRepository();
    Snackbar(message: 'Messages loaded successfully').display();
    return messages;
  }
}

At first glance, it looks fine. But problems arise quickly.

Imagine we now need to load messages on a second page, but with a specific requirement: don't show a snackbar on success. Meaning, sometimes we want to suppress the snackbar and sometimes we want to show it. So we add an argument to control that:

class ChatRoomState {
  getLatestMessages({bool? isSnackbarHidden}) async {
    final downloadedMessages = await GetChatRoomMessagesUseCase.call(
      isSnackbarHidden: isSnackbarHidden,
    );
    state.latestMessages = downloadedMessages;
  }
}

class GetChatRoomMessagesUseCase {
  call({bool? isSnackbarHidden}) async {
    final messages = await getChatRoomMessagesRepository();
    if (isSnackbarHidden == false) {
      Snackbar(message: 'Messages loaded successfully').display();
    }
    return messages;
  }
}

As you can see, the code is already getting more complicated. And our example only has two layers. In real projects, it's not uncommon to have three or four layers of nested classes.

But this isn't even the worst part.

Imagine months go by, the app grows, and a new developer joins the team. They're tasked with loading messages on yet another page. They use the ChatRoomState.getLatestMessages function without reading the underlying implementation. Everything looks good, and they mark the task as done. But somehow, the page displays a "Messages loaded successfully" snackbar.

They're confused. This wasn't expected. But the root cause is a hidden side effect.

Think about it: ChatRoomState is supposed to be responsible for chat room data only. And yet, using it triggers a completely unrelated UI change—a snackbar. In other words: working with chat room data unexpectedly affects the UI.

These kinds of issues are hard to detect and take time to:
• notice,
• debug,
• and fix.

You might think this is a rare or exaggerated case, but it happens more often than you'd expect.

Let me give you a real-world example from a project I worked on.

The app had three major features. Over time, our analytics showed that one feature was being used far more than the others. So we shifted focus and began redesigning the app around it. The other features were put on hold.

Months later, we discovered the truth: the feature wasn't actually being used that much. What happened?

One of our shared state methods was producing a hidden side effect. Every time any page was opened, it triggered an analytics event saying "Feature X was used". This inflated the usage stats and led to major business decisions based on false data.

This simple side effect cost us months of work and untold losses.

The solution

So how do we fix this?

By extracting logic out of the state.

We change this:

Into this:

First, let's rewrite our state:

Step 1: Rewrite the state

class ChatRoomState {
  setMessages(messages) {
    state.latestMessages = messages;
  }
}

Step 2: Move the logic into the use case

class GetChatRoomMessagesUseCase {
  call({bool? shouldDisplaySnackbar}) async {
    final downloadedMessages = await getChatRoomMessagesRepository();
    chatRoomState.setMessages(downloadedMessages);

    if (shouldDisplaySnackbar == true) {
      Snackbar(message: 'Messages loaded successfully').display();
    }
  }
}

In the end, everything that needs to happen for a specific action—like downloading chat messages—is placed into a single container: the use case. This makes the action easy to read, understand, reuse, extend, test, and maintain. If you ever need to change how messages are loaded, you simply go to the use case and make your changes—no need to dig through scattered classes.

Need to sort the messages? Replace the snackbar with something else? Add analytics tracking? Switch to a different data source? All of that becomes straightforward, because you know exactly where to look. And you can be confident that making a change won't accidentally trigger unrelated behavior.

What happens in the use case is what happens in the UI. No hidden side effects, no surprises, no accidental breakage.

This is what I call predictable state management.

Rules of Predictable State Management

To implement and make the most of Predictable State Management, let's define a few essential rules.

Don't create a state unless you need a single source of truth

Many developers don't know—or have forgotten—why state management was invented in the first place.

Let's say you're working on a Facebook-like website. Every few minutes, you fetch data about how many friend requests the user has. This number is displayed in three different places:

In the top-right corner, where the notification icon shows the count of friend requests.
In the left-side menu, next to the "Friends" link.
On the "Friends" page itself, inside the main content area.

So, what's the problem?

Every time the data is refreshed, the UI needs to be updated in three separate places. This quickly becomes complex and unmaintainable because:

You need to know what page the user is on.
You need to know how many places are displaying that data.
Each spot requires its own update logic or script.

To solve this, state management was introduced. The idea was simple: UI elements should listen to shared data sources. When the data changes, the UI updates automatically.

This gave developers a single source of truth. Instead of manually updating each UI element, you update the data once, and everything stays in sync.

That's it. Nobody set out to create a fancy "state as glue between UI and logic" philosophy. We just wanted a clean way to reuse data across the UI.

There's one important clarification: "single source of truth" does not mean "only create states that are used in multiple places". Even if a piece of data is used in just one place, managing it via state is still valid—because it might be needed elsewhere in the future. Using a state makes it easy to extend usage without major rewrites.

The real rule is: don't create unnecessary state.

Here's an example of unnecessary state:

// BAD: Do not do this.
class AnalyticsState {
  trackAnalyticsEvent(event) {
    AnalyticsService().trackEvent(event);
  }
}

This is not a real state. It doesn't hold or modify any data. Subscribing to it would provide no benefit. In this case, you should just call AnalyticsService directly—there's no need to wrap it in a state class.

1 data point per state — plus optional metadata

One of the most common mistakes in state management is creating a separate state for each page of the application. Developers often lump every single piece of data used on a page into the same container.

Let's look at an example:

// BAD: Don't do this.
class MainPageState {
  User viewer;
  List<ChatRoom> chatRooms;
  bool isSideBarOpen;
  bool isCreateChatRoomDialogOpen;

  // Setters/getters/methods below...
}

Why is this a bad idea? There are several reasons:

It makes data non-reusable.
For example, if you want to open the "Create Chat Room" dialog from somewhere other than the main page, you'd have to duplicate the isCreateChatRoomDialogOpen flag in another state. This leads to code duplication and violates the DRY principle.
It breaks SOLID principles.
- Single Responsibility Principle: The state now has multiple reasons to change. If you want to modify viewer data, you edit MainPageState. If you want to change how the sidebar opens, you edit the same class again.
- Open/Closed Principle: Adding a new feature or data point means editing this class, rather than extending functionality with new, focused classes.

A better approach is to extract each meaningful piece of data into its own dedicated state:

class ViewerState {}
class ChatRoomsState {}
class SideBarState {}
class CreateChatRoomDialogState {}

This leads to a key insight:
A good state holds a single, small, but meaningful piece of data.

What does "small yet reasonable" mean?

Let's take the example of the currently logged-in user. It makes sense to have a ViewerState that holds a User object. This is a single logical unit of data.

However, adding something like userHasOpenedLoginDialog to ViewerState would be wrong. That piece of UI-related metadata belongs in its own state. When we think about a "user," we think about their name, email, ID—not whether a dialog is currently open.

On the other hand, splitting ViewerState into ViewerFirstNameState, ViewerLastNameState, etc., would also be a mistake. Over-fragmenting a small object into many microstates provides no benefit and introduces unnecessary complexity.

To be clear: I'm not saying that objects should never be broken down. If an object grows too large, you should break it into smaller parts. But in cases like this, a single ViewerState is perfectly reasonable and more maintainable.

Optional additional metadata

As the previous rule mentions, we also have the option to include additional metadata in a state. But what exactly is metadata?

Metadata is simply "data about data". In practical terms, when we load some data, we often want to track information about that process:
Is it currently loading? Did it fail? How many times have we retried it? When did the request start?

Let's look at an example:

// A state that includes both data and metadata.
class ChatRoomsState {
  // Metadata
  bool isDataLoading;
  Error? loadingError;
  bool hasLoadingFailed;
  bool hasLoadingBeenRetried;
  num amountOfLoadingRetries;
  DateTime loadingRequestedAt;

  // Actual data
  List<ChatRoom> chatRooms;
}

It generally makes sense to keep metadata as close to the data as possible. That way, everything related to a particular state lives in one place. However, if your app architecture calls for it, you can extract metadata into a separate state—it depends on what makes the most sense for your use case.

You can also improve the example above by grouping the metadata into a nested object. For example:

class ChatRoomsState implements LoadableState {
  List<ChatRoom> data;
  ChatRoomsStateMetaData metaData;
}

class ChatRoomsStateMetaData {
  bool isDataLoading;
  Error? loadingError;
  bool hasLoadingFailed;
  bool hasLoadingBeenRetried;
  num amountOfLoadingRetries;
  DateTime loadingRequestedAt;
}

Whether this structure is better is subjective. It's up to you to decide if the separation makes your code more readable or maintainable. Use it if it fits your style or project needs.

State methods must set or return data. No side effects of any kind

As we discussed earlier, doing any side effects inside state methods is a bad idea.

When it comes to classes and restrictions, it's actually not uncommon to set healthy boundaries. For instance, it's very common to use the Repository pattern to deal with remote data. Here's an example of a repository:

class ChatRoomsGetterRepository {
    List<ChatRooms> getChatRooms() {
        final data = http.get('/api/chat-rooms');
        return data;
    }
}

This class does only a single thing: it downloads remote data. It doesn't do anything else. It doesn't record analytics data, it doesn't modify the UI. It's basically an abstraction, a contract. We don't know how it downloads the data or where it gets it from. We only know that if we use this class, we will receive a list of chat rooms.

This repository is useful because it encapsulates logic and allows us to replace the data source without too much hassle.

Let's say we decided to migrate from REST to GraphQL. We can either rewrite the logic of ChatRoomsGetterRepository or we can create a ChatRoomsGraphqlGetterRepository with the same interface and simply replace the class. In the end, changing the source of chat rooms will not break anything else in our app.

This pattern is commonly used and its usefulness is undeniable. In my opinion, good states should be treated the same as repositories. These are classes that do very little: they hold and modify a small amount of data. We don't know how exactly they're doing it and we don't care. We only know that they cannot do anything else, and when we call state methods, a certain piece of data is going to be updated. They are simple and obvious.

Let's consider an example:

// BAD STATE. Don't do this.
class ViewerState {
    User? viewer;

    login() {}

    logout() {}
}

What is wrong with this state, you may ask? Well, for instance, "logout" assumes that a lot of actions are going to happen when this method is invoked: a network request will be made, cache will be cleared, local storage will be erased, an analytics event will be recorded, most of the UI will be updated.

On the other hand, this snippet:

// GOOD.
class ViewerState {
    User? viewer;

    setViewer() {}

    unsetViewer() {}
}

does not have such assumptions. When you invoke "unsetViewer," it's obvious that only the state is going to change. The logged-in user object is going to be removed from the state. That's it. There are no side effects. No complications.

This state is simple, obvious, and predictable.

Another way to think about states is to treat them as micro databases. Imagine a database that can only hold a very limited amount of data (a primitive, an object, or a list of objects). This database can only hold and modify its data. A database cannot and should not make API requests, update other databases, or force the UI to display notifications.

The less logic there is in a state, the better

Note: a quick reminder. "Logic" in most cases means "business rules".

It's very tempting to put logic inside your states. But by doing so, you might end up with the same problems as with side effects: by trying to reuse code in an improper place, you will eventually shoot yourself in the foot. Too much logic in states makes them unobvious and unpredictable.

Let's say we need to display to the user the number of participants in a chatroom. Please consider this code snippet:

class ChatRoomState {
  int getNumberOfParticipants()
}

Let's say the number is 101. But inside the settings page of this chat room, we also must display the number of participants. Though this number must be lower if the currently logged-in user is the creator of this chat room. Therefore, on the main chat room page, the number of participants would be 101, but on the settings page, the number would be 100. Such is the business requirement.

This means that even though we are using the same data in two places of the application, that data must be slightly different in one of them. We must add a special check somewhere to change the number of participants. The question is: where would you put it?

You might be tempted to change the state and add a special method:

class ChatRoomState {
  int getNumberOfParticipants()
    int getNumberOfParticipantsWithoutAdmins()
}

Or you might want to add a flag to an existing method:

class ChatRoomState {
  int getNumberOfParticipants(bool isNumberOfAdminsRemoved)
}

Sadly, both of these solutions would be wrong because changing the state to fit a special use case opens the door to unobvious and unmaintainable states. For example, let's say after a while we receive new business requirements and now we need to display 0 participants for chatrooms that are marked as "private"? In that case, we will have to somehow check if the logged-in user is a member of the chatroom and if they should have access to this information. Since previously we were putting the logic regarding chat room participants inside the state, we will have to continue doing so. With time, the state will become more and more bloated and less and less predictable.

Just to clarify: this rule does not mean that adding new methods to states is completely prohibited.

Let's say we have a state that is responsible for the list of downloaded chat rooms:

class ChatRoomsState {
  List<ChatRoom> chatRooms;

  update(updatedChatRoomsList) {}
}

In many parts of our application, we push new chat rooms to this list: after we created a chat room, after we were invited to the chat room, or for other reasons. In that case, it's quite handy to add a special method for it:

class ChatRoomsState {
  List<ChatRoom> chatRooms;

  update(updatedChatRoomsList) {}

  addChatRoom(newChatRoom) {
    this.chatRooms.add(newChatRoom);
  }
}

You might be wondering: what is the difference between the first example with the number of participants in a chat room where adding methods is bad and the current example? Well, it's simple: the first example adds business rules to the state, the second one simplifies the way we interact with the state. The second one is a shortcut for this:

// Before:
newChatRoomsList = chatRoomsState.chatRooms.add(chatRoom);
chatRoomsState.update(newChatRoomsList);

// After:
chatRoomsState.addChatRoom(chatRoom);

Even though the first example and the second one technically both add "logic" to states, the second one simplifies our life and the first one will eventually make our life harder.

In conclusion: whenever you are unsure what to do, remember this rule—the less logic there is in a state, the better. Ideally, there should be a single "update()" method and nothing else. Though if it makes sense for your use case, do add new methods.

More complicated example

Simple examples are good to understand the basics of the idea. But what is often missing is something more complicated to make sure you can apply the idea in practice. Because reality is always far more complicated and always forces you to reinvent the wheel.

Let's say you were hired to work on a Twitch.tv-like website. On this site, you can watch people stream games, you can participate in the chat, subscribe to the streamer, and so on. Your first task is to add the ability to donate money to a streamer you are watching. How would you go about doing that task?

Task requirements:

The number of dollars in the wallet must decrease.
The number of experience points must increase. (Context: users of our app can level up their profiles based on certain actions)
The chat must display "X donated Y$ to the streamer" announcement.
These changes to the UI must happen BEFORE network requests are fired/completed (this technique is called "optimistic UI").
A "Success!" snackbar must be displayed if network requests were successful.
A "Something went wrong." snackbar must be displayed if network requests were unsuccessful.
All of the UI changes must be reverted if the API responded with an error.
Donation success or failure must trigger an appropriate analytics event.

Before we jump into the implementation, let's take a look at how developers usually approach the development. Let's read code that was written via states that contain logic:

// BAD. DON'T DO THIS.
class DonationsState { // <= First problem.
  donateToStreamer(amount) async {
    try {
      globalLoadingIndicatorState.setIsLoading(true);

      await walletState.subtractFunds(amount); // <= Second problem.
      await viewerState.addExperience(10); // <= Second problem.
      await activeChatState.announceDonation(); // <= Second problem.

      await submitDonationRepository.submit(amount);
      analyticsTracker.trackDonationToStreamer(amount);

      snackBarService.displaySnackbar('Success!'); // <= Third problem.
    } catch (error) {
      walletState.addFunds(amount); // <= Fourth problem.
      viewerState.subtractExperience(10); // <= Fourth problem.

      activeChatState.removeDonationAnnouncement();

      analyticsTracker.trackDonationToUserFailure(reason: error.message);
      snackBarService.displaySnackbar('Oops, something went wrong');
    }

    globalLoadingIndicatorState.setIsLoading(false);
  }
}

Descriptions of problems:

1) A state without data defeats its purpose. What is the point of subscribing to it if it doesn't have any data? And if you don't plan on subscribing to it, then it's not a state.

2) These state methods can internally call other state methods. When you read this code, you cannot be sure that the app will do exactly the things you want it to do. The behavior is unpredictable.

3) Can you be sure that this service doesn't internally change states? Pretty much the same problem as in the previous point but with more steps.

4) Without reading the implementation of these methods, can you be sure that they will do what you want of them? "walletState.addFunds" implies that we are giving money back to the user (we are increasing the amount of numbers in the UI in front of their eyes) because for whatever reason the network request failed. This means we only want to change the state (the state properties) without any side effects. We don't want any HTTP requests done, we don't want any extra snackbars to pop up. Are you sure that this method will do only that? And can you be sure that somebody won't change the implementation in the future? I highly doubt it.

As you can imagine, this code will be hard to maintain and you're always going to have a feeling that anything can break at any point in the future. You can't rely on it. It's unpredictable.

Let's take a look at the code where logic was extracted from the states. Here's how Predictable State Management looks in practice:

// GOOD. DO THIS.
class DonateToStreamerUseCase {
  donateToStreamer(amount) async {
    try {
      globalLoadingIndicatorState.setIsLoading(true);
      activeChatState.announceDonation();
      walletState.subtractFunds(amount);
      viewerState.addExperience(10);

      await subtractFundsRepository.subtract(amount);
      await addExperienceRepository.add(amount);
      await submitDonationRepository.submit(amount);

      analyticsTracker.trackDonationToStreamer(amount);

      snackBarService.displaySnackbar('Donation successful!');
    } catch (error) {
      walletState.addFunds(amount);
      viewerState.subtractExperience(10);

      activeChatState.removeDonationAnnouncement();

      analyticsTracker.trackDonationToUserFailure(reason: error.message);
      snackBarService.displaySnackbar('Oops, something went wrong');
    }

    globalLoadingIndicatorState.setIsLoading(false);
  }
}

As you can see, we did two things here: 1) we turned the class from a state into a use case and 2) we extracted all repositories from states. By doing so, we gain predictability and control over our code. And the ability to have total control over what happens in your app is the main point of this article. With this new way of writing code, you will be able to introduce any kind of changes. You want to make sure that the user has enough funds by making a special request to the API? Not a problem. You want to remove the global loading indicator and instead use the "isLoading" property of walletState? Sure, not a problem. You want to display errors by using activeChatState instead of a snackbar? You can do so by rewriting 4 lines of code instead of rewriting 4 methods.

Even though predictability is amazing, the only downside of this approach is it's harder to reuse code now. Let's say that each time we award the user with experience, we also want to check if the user has enough points to level up. If they do, we want to display some kind of leveling up animation, track an analytics event, and make an API request.

In that case, we are faced with a dilemma. Do we place all this leveling code into a service and lose predictability and control? Think of the "Optimistic UI" requirement of our task; with a separate service, it will be hard to implement it.

How do we reuse code and keep predictability? That is a topic for our next conversation. TO BE CONTINUED.

Predictable vs unpredictable (properties comparison)

Unpredictable states:

Contain multiple data points
Have methods with side effects
Can have unobvious method names
Have no rules on how to use states
Contain business rules of the application
Do not follow SOLID principles. Mainly S and O

Predictable states:

Contain only a single point of data
Have methods that only change data of the state. No side effects of any kind
Have obvious method names
Have specific rules
Act as containers for data. They do not contain business rules
Follow SOLID principles. Predictable states have only a single reason to change and new functionality is added by adding new states instead of extending existing ones

Additional Benefits of PSM

Easier maintenance and onboarding of new developers

When logic is extracted out of states, it's usually placed inside Controllers or Use Cases. Compared to the previous approach where logic was mixed between the view layer, states, and controllers, this allows developers to more easily understand the business rules of the application.

This also makes onboarding of new developers easier and reduces the "bus factor".

Undo/redo functionality

When your states do not contain any logic or side effects, it's extremely easy to roll back state changes.

class UndoableCounterState {
  counter = 0;
  _stateHistory = [];

  update(newCounterValue) {
    _stateHistory.add(counter);
    counter = newCounterValue;
  }

  undo() {
    counter = _stateHistory.last;
    _stateHistory.removeLast();
  }
}

Why do people get away with unpredictable states?

Short answer:

Developers don't actually get away with doing states wrong. The reason why it feels that way is because it takes time for problems to pop up. And by the time they encounter bugs and difficulties, they are so deep down the rabbit hole that it's impossible to see solutions to fundamental problems. Quick fixes and workarounds do help in the beginning but eventually make states unmaintainable in the long run.

Long answer:

Since I claimed that most teams and companies make a lot of fundamental mistakes when it comes to working with state management, how come nobody has noticed any problems?

As with anything, there are a lot of ways to do something wrong and only a limited number of ways to do something right.

1) They don't.

Usually, it takes a lot of time to get in a situation when adding new features or fixing a bug gets frustratingly difficult. By that time, it's too hard to tell where exactly everything went wrong. And even if developers encounter such problems sooner, they simply update the state code and move on. Mind you: adding more methods to states in order to add a feature breaks SOLID principles.

2) People don't write anything complicated

Let's face it: the lion's share of applications don't encounter any problems because their lack of complicated logic allows them to get away with it. I'm not saying that most applications were easy to build. But I am saying that most of them do not deal with interconnected states, multi-team environments, and long lists of business requirements for every user action. Usually, it's as simple as: download an object, use the object to display something to the user, update the object in the state when an action occurred.

Their approach quickly falls apart when logic gets complicated. For instance, when a single action leads to a change of 5 different states and a call to 20 different services.

3) People work in small teams and/or on small projects.

When a developer encounters a problem (and all of them inevitably do as a project gets larger), it's easy to rewrite big chunks of the application if 3 people are working on it. However, when there are 20 teams and 100 developers working on a single app, then changing existing code quickly gets complicated.

4) People don't care about doing things properly. They are blind to problems.

When we encounter problems during development, we usually try to add a quick fix on top of the problem or we try to do a workaround instead. We add bad code on top of bad code instead of rewriting the bad parts. Basically, we are more focused on finishing a task and gaining short-term benefits. These benefits always hurt us in the long run.
As it was said in "Clean Code" by Robert C. Martin (and I am heavily paraphrasing here): "We don't have time to write clean code, so we write bad code that will slow us down even more in the future".

How to fix performance issues in Flutter

Mikhail Palei — Sat, 05 Nov 2022 17:13:51 +0000

How to fix common performance issues in Flutter

This article is a compilation of tips and tricks regarding performance of Flutter applications. Basically, these are the things I wish someone told me when I just started using Flutter.

Please keep in mind that it is best to test performance on a real device and in profile mode. Though, personally I use debug mode far more often since it allows me to have an instant feedback about performance since profile mode does not support hot refresh or reload.

Performance overlay.

Performance overlay is the easiest way to track performance degradation. It is accessible by calling “toggle performance overlay” action in VS Code and Android Studio. You can also enable it via DevTools.

In short: the top row tracks performance of code. The bottom row displays performance of actual drawing of pixels. The top row is in your control. It is performance of your code. The bottom row is usually outside of your control.

Both rows are horizontally divided into 16ms sections. To achieve 60 FPS you need to make sure that performance never goes above first section. If you spot that you cross these thresholds this usually means one of two things: you either doing too much things in the main thread and need to use isolates or you are doing too many things inside of your widget’s “build” method.

In screenshot below you will notice that top row is spilling over the first section. This is bad.

Widget rebuilds counter.

“Display widget rebuilds” is a neat tool that allows you to see how many times do your widgets activate “build” method. Sadly this tool is only available in Android Studio. Though I highly recommend using it even if you use different IDE. The data is simply too valuable to ignore.

This tool is a table that has 3 rows: list of widgets that were built in the app, number of widget rebuilds during last frame and a combined number of all rebuilds. Obviously the less you rebuild a widget the better. Thus if you have a lot of total rebuilds you might investigate how you use animations, how often you update your widgets arguments and how often you change the state of stateful widgets (hint: use AnimatedBuilder instead of calling “setState” method for animations).

In the screenshot below you can see that Text widget of MainPage (main_page.dart) have been built in total 3 times per session and only a single time in the last frame. Which is good. The less the better. The Text widget of TasksListItem on the other hand have been rebuild 259 times in a single frame. Which of course forced my app to lag.

Event loop and isolates.

One of the most common problems inexperienced Flutter developers encounter is a strange lag during application start. It goes like this: you launch the app, you see some loading animation, then loading animation freezes and after a second the app unfreezes and operates normally. This happens because when you request data from a remote server and receive the JSON your app can’t do anything else beside parsing the JSON for a few moments. Think of it this way: let’s say you have a list of 100 documents and each document has 10 fields. When you receive this JSON your app will have to go line by line 1000 times in order to convert this JSONs into usable Dart objects. This of course freezes the UI for a few moments.

To fix this you need to parse the JSON in a separate isolate. A quick reminder: Isolates are basically Darts equivalent of threads.

Below you will find a snippet extracted from one of my apps. There is quite a bit of code but the important line is this one: return compute(_parseListOfJsons, listOfJsons); This line creates a new thread and instructs it to run the parsing function on a list of JSONs.

class GetTasksToDoRepository {
  final FirebaseFirestore firestore;
  const GetTasksToDoRepository({required this.firestore});

  Future<List<Task>> call({required String userId}) async {
    try {
      final tasksSnapshot = await firestore
          .collection('tasks')
          .where('userId', isEqualTo: userId)
          .where('isDone', isEqualTo: false)
          .limit(250)
          .get();

      final listOfJsons = tasksSnapshot.docs.map((e) => e.data()).toList();

      return compute(_parseListOfJsons, listOfJsons);

    } catch (error, stackTrace) {
      log(error.toString(), stackTrace: stackTrace);
      rethrow;
    }
  }
}

List<Task> _parseListOfJsons(List<Map<String, dynamic>> docs) {
  return docs.map(Task.fromJson).toList();
}

Follow performance best practices.

https://docs.flutter.dev/perf/best-practices

Animations.

It is important not to forget to attach SingleTickerProviderStateMixin or TickerProviderStateMixin. Tickers keep animations in sync with screens. For example your animations won’t use any hardware resources if they are not visible to the user, i.e. when the app is running in the background or when the user navigated to a different route mid animation. They also “smooth” out animations by adapting them to the screen refresh rate.

It is also incredibly important to use AnimatedBuilder when ever possible. AnimatedBuilder does two things:

1) It allows us to rebuild only the necessary widgets during animation.

2) It allows us to to stop using _animation.addListener(() => setState(() {})) to activate the animation. Why is it important to drop setState? Because we don’t want to repaint widgets 60 times per second. It will inevitably lead to jank.

See https://api.flutter.dev/flutter/widgets/AnimatedBuilder-class.html for more information.

Shaders and initial jank.

When your app is first loaded you may notice that animations are janky. This jank is usually easy to spot when scrolling or jumping between router pages. This happens because Flutters rendering engine does not yet have required shaders to display smooth animations. This is fixable via compiling shaders manually. See the instructions here:

https://docs.flutter.dev/perf/shader

Note: the first time I read the instructions they seemed too daunting to me. Fear not my friend. They are actually quite simple: run the app, play with animations, build the app with produced shaders file.

Repaint rainbow and RepaintBoundary.

As we know Flutter repaints (rebuilds) widgets a lot even if there are no changes to widgets arguments. In order to spot this repaints you need to enable a special development feature that is going to highlight all of the repaints of the application. I highly recommend you to

I highly encourage you to always have this option enabled during development to spot the unwanted repaints as early as possible. Place this snippet before your runApp() in main.dart:

debugRepaintRainbowEnabled = kDebugMode;

In fact you will be surprised how many widgets are being repainted for no good reason. For instance: once I created a very simple countdown widget. All it was supposed to do is to display a single line of text that said: “You have 60 seconds left” and each second the number would decrease. This widget used only local state (it was a stateful widget) and it didn’t have any outside dependencies. Yet when I enabled repaint rainbow I was shocked to witness that somehow once a second whole screen of the application was repainted. What I expected to see is a single Text widget to be repainted.

The solution was to wrap my widget with RepaintBoundary widget. When it was applied only the Text widget was repainted once a second instead of the whole screen.

Important: do not use RepaintBoundary excessively. If misused this widget will put too much strain on the hardware and FPS will decrease.

Repaints caused by state changes.

When using state management libraries it is always a good idea to place state builders as close to consumers as possible. Let me demonstrate:

// BAD.
class BadBuilderExample extends StatelessWidget {
  const BadBuilderExample({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return BlocBuilder<ProfileCubit, ProfileState>(
      builder: (context, profileState) {
        return Column(
          children: [
            Text(profileState.profile.name),
            CreatePostForm(),
            Posts(),
          ],
        );
      },
    );
  }
}

// GOOD.
class GoodBuilderExample extends StatelessWidget {
  const GoodBuilderExample({Key? key}) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        BlocBuilder<ProfileCubit, ProfileState>(
          buildWhen: (previous, current) =>
              previous.profile.name != current.profile.name,
          builder: (context, profileState) {
            return Text(profileState.profile.name);
          },
        ),
        CreatePostForm(),
        Posts(),
      ],
    );
  }
}

In BadBuilderExample every change to ProfileCubit will force the whole widget to be repainted. In GoodBuilderExample only the Text widget will be repainted. Also, notice how I threw in buildWhen into the BlocBuilder this function will make sure that widget will be rebuilt only when profile.name changes. This will reduce rebuilds to an absolute minimum.

Even though I used BloC for this demonstration please remember that the general idea is important. Whatever you are doing, whatever library you are using, keep builders as close to consumers as possible.

Where to go from here.

Flutter is one of those tools that is all about how you use it. If you don’t know what you are doing you will be punished with bad performance. If you are skilled you will be rewarded with silky smooth UI. Even though this article will help you to solve 90% of your problems you might want to keep improving your knowledge. The best way to do so is to learn Flutter DevTools. Here is a good overview to get you up and running:

https://www.youtube.com/watch?v=nq43mP7hjAE