DEV Community: Leandro Boeing Vieira

Unity + Arquitetura Model-View-Presenter?

Leandro Boeing Vieira — Thu, 04 Jan 2024 21:21:26 +0000

Motivação

Ao longo da minha carreira de engenheiro de software, eu fui dando cada vez mais valor a código manutenível. Para muitos, perda de tempo, ou mesmo falta de tempo pra aplicar boas práticas e testes. Para outros, o grande salvador dos projetos de longo prazo, por ter sido possível dar manutenção às infinitas mudanças nos requisitos/escopo que sempre irão ocorrer.

Claro que para projetos pequenos, frutos de hobby, Provas de Conceito (PoC), eu não recomendo fazer seguindo essas práticas, principalmente pra quem ainda as está aprendendo e treinando. Isso pode sim atrasar bastante o desenvolvimento.

Porém, eu recomendo o estudo, a prática, o treinamento. Pois se um dia surgir uma vaga numa empresa grande de games, essas skills certamente chamarão a atenção do recrutador. Ou mesmo se você tiver aquela ideia genial de um jogo relativamente grande, elas podem te salvar horas de debug e dezenas de bugs.

Como primeira tentativa de trazer um padrão arquitetural para a Unity, eu pensei em MVC ou MVP. Inclusive, tem um artigo excelente do Baeldung que traz as diferenças dos dois: https://www.baeldung.com/mvc-vs-mvp-pattern

E dadas essas diferenças, por exemplo entre as funções da Controller do MVC e da Presenter do MVP, eu optei por iniciar pelo MVP. Me pareceu que encaixou melhor. Principalmente porque eu também queria escrever testes unitários para as regras do Model e Presenter. E pra isso o MVP se mostra melhor que o MVC, já que a Presenter é desacoplada da View, enquanto a Controller tem um alto acoplamento.

TicTacToe (Jogo da Velha)

Jogo simples, de UI simples, principalmente a minha que chega a ser feia de tão simples, porém vamos focar é na programação, no código, e principalmente na separação de responsabilidades desse código.

Na Unity, crie seu Canvas e sua grid da maneira que achar melhor. Eu utilizei Panel e Button com TextMeshPro:

A estrutura ficou assim:

MainScene
  GameManager
  Canvas
    GameBordPanel (Panel)
      Cell00 (Button)
      ...
      Cell22 (Button)
    PlayerInfoPanel (Panel)
      PlayerInfoText (TextMeshPro)
      WinnerInfoText (TextMeshPro)
      Reset (Button)
      Exit (Button)

Onde GameManager é um GameObject com 2 Script Components: GameManager e TicTacToeView. GameManager é o entrypoint da "aplicação", similar à classe Main do Java ou ao index.js do Javascript.

using UnityEngine;
using System;

public class GameManager : MonoBehaviour
{

    void Start()
    {
        var view = GetComponent<TicTacToeView>();
        if (view != null)
        {
            var model = new TicTacToeModel();
            new TicTacToePresenter(view, model);
        }
        else
        {
            Debug.LogError("TicTacToeView component not found on the GameObject.");
        }
    }
}

E esse é o Inspector do GameObject chamado GameManager:

Ainda não sabemos o que são a TicTacToePresenter, TicTacToeModel e nem TicTacToeView, mas sabemos que GameManager as gerencia.

Model

Essa camada existe independentemente de framework e biblioteca, dependendo apenas da arquitetura geral do sistema, nesse caso utilizando linguagem C#. Ela inclusive independe de detalhes de implementação da Unity.

public class TicTacToeModel
{
    private char[,] board = new char[3, 3];
    public char CurrentPlayer { get; private set; } = 'X';
    private bool gameOver = false;

    public TicTacToeModel()
    {
        ResetBoard();
    }

    public bool MakeMove(int x, int y)
    {
        if (board[x, y] == '\0' && !gameOver)
        {
            board[x, y] = CurrentPlayer;
            gameOver = CheckForWinner(x, y);
            if (!gameOver) 
            {
                SwitchPlayer();
            }
            return true;
        }
        return false;
    }

    private void SwitchPlayer()
    {
        CurrentPlayer = CurrentPlayer == 'X' ? 'O' : 'X';
    }

    private bool CheckForWinner(int x, int y)
    {
        // Check row
        if (board[x, 0] == CurrentPlayer && board[x, 1] == CurrentPlayer && board[x, 2] == CurrentPlayer)
        return true;

        // Check column
        if (board[0, y] == CurrentPlayer && board[1, y] == CurrentPlayer && board[2, y] == CurrentPlayer)
            return true;

        // Check diagonals
        if (x == y && board[0, 0] == CurrentPlayer && board[1, 1] == CurrentPlayer && board[2, 2] == CurrentPlayer)
            return true;

        if (x + y == 2 && board[0, 2] == CurrentPlayer && board[1, 1] == CurrentPlayer && board[2, 0] == CurrentPlayer)
            return true;

        return false;
    }

    public bool IsGameOver(out bool isDraw)
    {
        isDraw = false;

        if (gameOver)
        {
            // Game over due to a win
            return true;
        }

        if (IsBoardFull())
        {
            // Game over due to a draw
            isDraw = true;
            return true;
        }

        return false;
    }

    private bool IsBoardFull()
    {
        for (int i = 0; i < 3; i++)
        {
            for (int j = 0; j < 3; j++)
            {
                if (board[i, j] == '\0')
                {
                    return false;
                }
            }
        }
        return true;
    }

    public void ResetBoard()
    {
        for (int i = 0; i < 3; i++)
        {
            for (int j = 0; j < 3; j++)
            {
                board[i, j] = '\0';
            }
        }
        CurrentPlayer = 'X';
        gameOver = false;
    }

    public char GetCurrentPlayerSymbol()
    {
        return CurrentPlayer;
    }

}

Note que ela não tem nenhuma dependência a nenhum namespace da Unity, como using UnityEngine; ou using System; no código. Ela poderia até ser utilizada em um projeto .NET tranquilamente.

O intuito dela é guardar e proteger as regras do negócio. Que negócio? Nesse caso as regras do Jogo da Velha. Eu confesso que fiz na pressa, e poderia ter sido mais bem escrita, com alguns métodos a mais para extrair a lógica da checagem de um ganhador na horizontal, vertical e diagonal, entre outros, mas a ideia é mostrar essa classe sendo responsável pelo core do jogo.

O importante é perceber que ela está isolada de detalhes de infraestrutura.

Presenter

Presenter na MVP serve para orquestrar os inputs recebidos da View e informar ao Model, atualizando assim seu estado, bem como receber operações do Model e atualizar a View se necessário.

Sua implementação é até mais simples que o Model, já que ela apenas faz a intermediação entre Model e View:

public class TicTacToePresenter
{

    private TicTacToeModel model;
    private ITicTacToeView view;

    public TicTacToePresenter(ITicTacToeView view, TicTacToeModel model) {
        this.view = view;
        this.model = model;
        this.view.OnCellClicked += HandleCellClicked;
        this.view.OnResetClicked += ResetBoard;
        UpdatePlayerInfo();
    }

    public void HandleCellClicked(int x, int y) {
        char currentPlayerSymbol = model.GetCurrentPlayerSymbol();
        if (model.MakeMove(x, y)) {
            view.UpdateCell(x, y, currentPlayerSymbol);
            if (model.IsGameOver(out bool isDraw)) {
                if (isDraw)
                {
                    view.ShowWinner('\0');
                }
                else
                {
                    view.ShowWinner(model.CurrentPlayer);
                }
            } else {
                UpdatePlayerInfo();
            }
        }
    }

    public void UpdatePlayerInfo() {
        string info = model.CurrentPlayer == 'X' ? "Player X's Turn" : "Player O's Turn";
        view.UpdatePlayerInfo(info);
    }

    public void ResetBoard()
    {
        model.ResetBoard();
        view.ResetBoard();
    }

}

Note que ela orquestra os inputs recebidos na View e executa os comandos necessários no Model:

// Recebe inputs da View
this.view.OnCellClicked += HandleCellClicked;
// invoca ações no Model
model.MakeMove(x, y)
...

Note também que a Presenter recebe como parâmetro no seu construtor tanto a View quanto a Model, e mais, a View que ela recebe é uma interface e não uma classe concreta. Explico logo mais.

SOLID Principles

Os SOLID Principles ajudam a guiar seu código a uma solução manutenível. Se você aplicá-los, o efeito colateral será sempre um código desacoplado, testável e flexível.

Nesse caso específico estamos utilizando a DIP, Dependency Inversion Principle, com uma interface de View como dependência, para conseguir os seguintes resultados:

Desacoplamento: O TicTacToePresenter é desacoplado da implementação específica da View. Ele não precisa conhecer os detalhes de como a View é implementada; ele depende apenas do contrato definido pela interface.
Testabilidade: Fica mais fácil escrever testes unitários para o TicTacToePresenter, pois você pode criar implementações mock ou stub de ITicTacToeView para fins de teste. Isso permite isolar e testar o comportamento do Presenter independentemente da View real.
Flexibilidade: Você pode trocar a implementação concreta da View sem afetar a Presenter. Por exemplo, se um dia você decidir criar uma interface de usuário diferente para o seu jogo, ou delegar isso a um outro time mais especializado em UI, você pode implementar uma nova View que respeita o contrato da interface ITicTacToeView, e a Presenter não precisa mudar.

Você verá essa capacidade de testabilidade mais pra frente.\ quando falarmos dos testes automatizados.

View

Como sabemos, a View tem uma interface e uma implementação concreta. A interface fica no mesmo pacote que a Presenter, pois o motivo dela existir é a segregação de interface promovida pela camada Presenter.

using System;

public interface ITicTacToeView
{
    event Action<int, int> OnCellClicked;
    event Action OnResetClicked;
    event Action OnExitClicked;
    void UpdateCell(int x, int y, char playerSymbol);
    void UpdatePlayerInfo(string info);
    void ShowWinner(char winner);
    void ResetBoard();
    void ExitGame();
}

Perceba que ela expõe o contrato que uma View deve ter para saber se comunicar corretamente com a Presenter.

using UnityEngine;
using UnityEngine.UI;
using TMPro;
using System;

public class TicTacToeView : MonoBehaviour, ITicTacToeView
{
    public event Action<int, int> OnCellClicked;
    public event Action OnResetClicked;

    public event Action OnExitClicked;

    public Button[] cellButtons;

    public Button resetButton;

    public Button exitButton;

    public TextMeshProUGUI playerInfoText;
    public TextMeshProUGUI winnerInfoText;

    void Start()
    {
        for (int i = 0; i < cellButtons.Length; i++)
        {
            int index = i;
            cellButtons[i].onClick.AddListener(() => OnCellButtonClicked(index));
        }
        resetButton.onClick.AddListener(OnResetButtonClicked);
        exitButton.onClick.AddListener(OnExitButtonClicked);
        OnExitClicked += ExitGame;
    }

    private void OnCellButtonClicked(int cellIndex)
    {
        int x = cellIndex / 3;
        int y = cellIndex % 3;
        OnCellClicked?.Invoke(x, y);
    }

    private void OnResetButtonClicked()
    {
        OnResetClicked?.Invoke();
    }

    private void OnExitButtonClicked()
    {
        OnExitClicked?.Invoke();
    }

    public void UpdateCell(int x, int y, char playerSymbol)
    {
        int cellIndex = x * 3 + y;
        this.cellButtons[cellIndex].GetComponentInChildren<TextMeshProUGUI>().text = playerSymbol.ToString();
    }

    public void UpdatePlayerInfo(string info)
    {
        this.playerInfoText.text = info;
    }

    public void ShowWinner(char winner)
    {
        this.winnerInfoText.text = winner == '\0' ? "It's a draw!" : $"Player {winner} wins!";
    }

    public void ResetBoard()
    {
        foreach (var button in cellButtons)
        {
            button.GetComponentInChildren<TextMeshProUGUI>().text = "";
        }
        UpdatePlayerInfo("Player X's Turn");
        winnerInfoText.text = "";
    }

    public void ExitGame()
    {
        #if UNITY_EDITOR
            UnityEditor.EditorApplication.isPlaying = false;
        #else
            Application.Quit();
        #endif
    }
}

E perceba que a View e a primeira classe em nosso projeto que conhece dependências de Unity, como as namespaces UnityEngine, UnityEngine.UI e TMPro.

Tests

Você pode clonar o repo no link do final do artigo, e rodar o jogo na Unity e vai ver que ele roda e funciona bem. Porém, lembra que uma das maiores vantagens de ter usado o padrão arquitetural MVP com DIP foi conseguir uma testabilidade isolada dos componentes?

Olha como podemos testar as regras do jogo, independentemente de UI:

using NUnit.Framework;

public class TicTacToeModelTests
{
    private TicTacToeModel model;

    [SetUp]
    public void Setup()
    {
        model = new TicTacToeModel();
    }

    [Test]
    public void Should_Return_True_For_A_Valid_Move()
    {
        bool result = model.MakeMove(0, 0);

        Assert.IsTrue(result);
    }

    [Test]
    public void Should_Return_False_For_An_Invalid_Move()
    {
        model.MakeMove(0, 0);

        bool result = model.MakeMove(0, 0);

        Assert.IsFalse(result);
    }

    [Test]
    public void Should_Have_Winner_In_Horizontal_Line()
    {
        model.MakeMove(0, 0); // X
        model.MakeMove(1, 0); // O
        model.MakeMove(0, 1); // X
        model.MakeMove(1, 1); // O

        bool result = model.MakeMove(0, 2);

        Assert.IsTrue(result);
    }

    public void Should_Have_Winner_In_Vertical_Line()
    {
        model.MakeMove(0, 0); // X
        model.MakeMove(0, 1); // O
        model.MakeMove(1, 0); // X
        model.MakeMove(1, 1); // O

        bool result = model.MakeMove(2, 0);

        Assert.IsTrue(result);
    }

    // Other tests for the Model can be added here
}

E, mais do que isso, se usar uma biblioteca tipo Moq, podemos ainda testar a Presenter para garantir que ela chama as atualizações de View corretamente:

using NUnit.Framework;
using Moq;

public class TicTacToePresenterTests
{
    private TicTacToePresenter presenter;
    private Mock<ITicTacToeView> viewMock;
    private TicTacToeModel model;

    [SetUp]
    public void Setup()
    {
        viewMock = new Mock<ITicTacToeView>();
        model = new TicTacToeModel();
        presenter = new TicTacToePresenter(viewMock.Object, model);
    }

    [Test]
    public void Should_Update_Player_Info_In_View()
    {
        var expectedInfo = "Player X's Turn";
        viewMock.Setup(view => view.UpdatePlayerInfo(It.IsAny<string>()));

        presenter.UpdatePlayerInfo();

        viewMock.Verify(view => view.UpdatePlayerInfo(expectedInfo), Times.Exactly(2));
    }

    // Other tests for the Presenter can be added here
}

E note, adicionar essa meia dúzia de testes não atrasa muito o desenvolvimento do seu projeto, seja honesto. Não estou falando que você precisa atingir 100% de cobertura de linhas, mas as features principais, como determinar que uma linha com 3 X's faz um vencedor, pode estar testada, certo?

Clean Architecture

Model-View-Presenter não compreende todas as peculiaridades da Arquitetura Limpa, porém ela endereça pelo menos a separação entre camada de negocio da UI. Framework Adapters e Use Cases com Entities são assunto para um outro momento.

Conclusão

Embora a MVP não resolva todas as nuances da Clean Architecture, ela pelo menos separa o domínio da UI. Isso em projetos grandes/longos tende a facilitar muito em termos de manutenção.

Note que criar as classes Model-View-Controller não mudaram MUITO o tempo de implementação. Com exceção de um evento a mais aqui ou ali, a lógica que antes estaria na View, e agora está na Model.

E o maior ganho do advento dessa arquitetura foi a possibilidade da criação dos testes automatizados. Você não precisa testar seu jogo inteiro de forma automatizada, mas que tranquilidade saber que a lógica para o vencedor do TicTacToe permanecerá intacta, garantida por uma suíte de teste automatizado!

Espero que tenha gostado desse artigo. E se quiser aprender mais sobre Clean Code, Clean Architecture, Hexagonal Architecture, Domain-Driven Design, Agilidade, testes Automatizados, TDD, recomendo ler meu livro "Minha Jornada para Ganhar em Dólar como Programador". Link da Hotmart seguir.

Link do projeto no Github: https://github.com/lepsistemas/MVP-TicTacToe
Minha Jornada para ganhar em Dólar como Programador: https://go.hotmart.com/K89021018W

gRPC + Spring Boot application compiling proto files as a dependency

Leandro Boeing Vieira — Wed, 27 Oct 2021 00:49:33 +0000

If you're working with gRPC you're probably also working with Protobuf. And manually sharing your proto files with clients may not scale well.

What if I tell you that you could have a separated project and share your proto files as gradle/maven dependencies? That's the main goal of this article. Of course there'll be many more ways do to it out there, but if you use this article as a guide to do better, I'll be really honored.

So, I created 2 projects on Github:

Noticed the names? One of them ends with "-proto". Yes, that's the project where we'll keep the proto files related to the "grpc-hexagonal-architecture" service. Oh, you're telling me you also noticed the names "hexagonal architecture"? That's a talk for another article. Let's focus on sharing the proto files in this one. And similarly I created 2 maven projects with the very same names.

The structure of the "proto project" is really simple:

src
+---main
+---+---proto
+---+---+---common
+---+---+---+---messages.proto
+---+---+---service
+---+---+---+---task.proto
pom.xml

No java classes, no extra configuration, just a pom file and a src folder. But if you pay attention to the pom file you'll wanna look at two parts:

The <project.scm.id>
The maven-release-plugin

The <project.scm.id> tag only exists to support multiple Github users on the same machine. If you only have one user, please define it with the value "github.com". In my case, "github.com" refers to the repositories I use in my job and for my personal repositories I use "github-lepsistemas". Please, refer to this article if you need help with it: https://www.freecodecamp.org/news/manage-multiple-github-accounts-the-ssh-way-2dadc30ccaca/

The maven-release-plugin will allow you to create tags and releases for your project in Github. For that, you'll need to be working on a SNAPSHOT (<version>1.0.0-SNAPSHOT</version>) and then you need to execute the maven task:

mvn -B release:clean release:prepare release:perform

This will create tag and release 1.0.0 in Github and will increase your local pom to 1.0.1-SNAPSHOT version.

At this point you have a release available in Github and you could download it as a dependency in another project. We'll use it in "grpc-hexagonal-architecture", another maven project.

Along with the dependencies that the project needs to compile/test/run, you'll also need this under <project> tag:

<repositories>
     <repository>
         <id>jitpack.io</id>
         <url>https://jitpack.io</url>
     </repository>
</repositories>

This will allow you to download a dependency directly from Github.

Add the dependency under the <dependencies> tag:

<dependency>
    <groupId>com.github.lepsistemas</groupId>
    <artifactId>grpc-hexagonal-architecture-proto</artifactId>
    <version>1.0.0</version>
</dependency>

And configure the compiler like this under the <plugins> tag:

<plugin>
    <groupId>org.xolstice.maven.plugins</groupId>
    <artifactId>protobuf-maven-plugin</artifactId>
    <version>0.6.1</version>
    <configuration>
        <protocArtifact>com.google.protobuf:protoc:3.17.3:exe:${os.detected.classifier}</protocArtifact>
        <pluginId>grpc-java</pluginId>
        <pluginArtifact>io.grpc:protoc-gen-grpc-java:1.41.0:exe:${os.detected.classifier}</pluginArtifact>
        <protoSourceRoot>${basedir}/../grpc-hexagonal-architecture-proto/src/main/proto/</protoSourceRoot>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>compile</goal>
                <goal>compile-custom</goal>
            </goals>
        </execution>
    </executions>
</plugin>

All set. Your new gRPC project has a dependency from another project that exposes only the proto files. If you have any doubts, please refer to the Github repositories or you can always ask me.

What Financial Softwares, Martin Fowler, Uncle Bob and Alexander Hamilton have in common?

Leandro Boeing Vieira — Mon, 24 May 2021 12:57:12 +0000

As Martin Fowler said in his article about Patterns of Enterprise Application Architecture (https://martinfowler.com/eaaCatalog/money.html):

"A large proportion of the computers in this world manipulate money, so it's always puzzled me that money isn't actually a first class data type in any mainstream programming language."

Well, I didn't read the book Patterns of Enterprise Application Architecture, but I do know that he suggests the implementation of a class Money, with the attributes currency and amount, as well as a method called allocate that receives a list of proportions and distributes that money without leaking values with rounding. In this article I'll show how we've implemented our Money to solve a real problem of losing cents in apportionments, and also solve the mystery of this article's title.

We already had a Money class, which made it really easier to write the Money Pattern. So, if I am to give you a first hint, it is: DO NOT use Double or Big Decimal to financial values. Build your "Value Object". After having financial values spread all over your system, it's gonna be harder - but not impossible - to refactor.

Our Money class doesn't have the attribute currency because we don't have the need for a internationalization, at least not yet. And we are not going to implement currency until we actually need it. Just like we didn't have the allocate method. Until we needed it. So, our Money was like this:

public class Money implements Serializable {

  private final BigDecimal amount;

  private Money(BigDecimal amount) {
    if (amount == null) {
      throw new AmountCantBeEmptyException();
    }
    this.amount = amount;
  }

  public static Money of(BigDecimal amount) {
    return new Money(amount);
  }

  public Money plus(Money addition) {
    return Money.of(this.amount.add(addition.amount));
  }

  public Money minus(Money discount) {
    return Money.of(this.amount.subtract(discount.amount));
  }

  public Money times(BigDecimal factor) {
    return Money.of(this.amount.multiply(factor));
  }

  public BigDecimal getAmount() {
    return amount;
  }

  @Override
  public boolean equals(Object obj) {
    if (obj == null || !(obj instanceof Money)) {
      return false;
    }
    return this.amount.compareTo(((Money) obj).amount) == 0;
  }

  @Override
  public int hashCode() {
    return this.amount.hashCode();
  }

}

This used to solve most of our financial problems. Until the day we needed the allocate method. A debit worth of $ 1000.20 should be apportioned between several accounts with the following rules:

#	Proportion	Gross Value	Rounded Down	Rounded Up	Rounded Half Even
1	22,9%	229.0458	229.04	229.05	229.05
2	27.7%	277.0554	277.05	277.06	277.06
3	7.8%	78.0156	78.01	78.02	78.02
4	22.6%	226.0452	226.04	226.05	226.05
5	19%	190.038	190.03	190.04	190.04
Total	100%	1000.20	1000.17	1000.22	1000.22

As you can see, applying the apportionment percentage on every item, we'll never get to 1000.20 - this happens because cents are an indivisible unit, so the financial value represented by Money can't be 229.0458, for example. If we round down, 3 cents are lost in the end. If we round up, we get 2 extra cents. Even using Round Half Even will have precision loss.

And guess who faced a problem like this? George Washington himself and one of the proposed solutions came from Alexander Hamilton, one of the Founding Fathers, and first United States Secretary of the Treasury, using his Largest Remainder Method.

The problem faced at that time, described in U.S. Census Bureau, was shortly:

A country with 4 states, each one with its own population, and 20 Seats at the House of Representatives. How many senators each state should have so they are represented proportionally? A senator, just like a penny, can't be divided in pieces. Right? Just double checking...

State	Population	Seats by State	Seats by State before Hamilton's method	Seats by State after Hamilton's method
1	2560	4.31	4	4
2	3315	5.58	5	6
3	995	1.67	1	2
4	5012	8.44	8	8
Total	11882	20	18	20

Hamilton's method consists in calculating the proportion between the population of 11882 and the number of 20 seats, resulting in the quota of 594.1. Now, for each state, divide its population for the quota. For example in the state 1, 2560/594.1 getting a quotient of 4.31.

As we have agreed, we can't have 4 senators and 0.31 of a senator for a state. So the number of senators for the state 1 is 4, which is the whole part of the result. That happens for every state. In the end, because of the rounding, the number of senators allocated in the states is 18. Which states should the other 2 senators go to? That's when Hamilton comes with a possible solution. His idea is that we distribute these 2 seats to the states that had the largest decimal part before the rounding.

I'll explain. If we suppress the whole part of the Seats by State column and desc order by the decimal part, we get:

1,67
5,58
8,44
4,31

Since we have a total of 2 seats to redistribute, the states that will receive these senators are the first 2 of the list. Resulting in the column Seats by State after Hamilton's method.

There's a paradox to be noticed that was discovered by applying Hamilton's method in the population of Alabama, reason it is called the Alabama Paradox. That will not be covered here. But this is when Uncle Bob comes in the article.

Amongst his countless contributions to the software development community, Uncle Bob spread the SOLID principles. They were relevant in the 90's, they are relevant now. The principle we are focusing now is the Open-Closed Principle.

We need to change our Money class to implement the allocate method to distribute its values in ratios without losing any cents. So we created it like:

public class Money implements Serializable {
  private static final BigDecimal ONE_HUNDRED = new BigDecimal(100);

  public List<Money> allocate(List<BigDecimal> ratios, RemainderDistribution distribution) {
    long amountInCents = toCents();
    List<Quota> quotas = new ArrayList<>();
    for (BigDecimal ratio: ratios) {
      quotas.add(new Quota(amountInCents, ratio));
    }
    distribution.distribute(quotas, amountInCents);
    return quotas.stream().map(Quota::toMoney).collect(Collectors.toList());
  }

  public long toCents() {
    return this.amount.multiply(ONE_HUNDRED).longValue();
  }
}

public class Quota {
  private static final BigDecimal ONE_HUNDRED = new BigDecimal(100);

  private long amount;
  private long total;
  private BigDecimal ratio;

  public Quota(long total, BigDecimal ratio) {
    this.total = total;
    this.ratio = ratio;
    this.amount = ratio.multiply(BigDecimal.valueOf(total)).longValue();
  }
}

public interface RemainderDistribution {
  void distribute(List<Quota> quotas, long total);
}

Remember the Alabama Paradox? Even having validated with our Product Manager that we would adopt Hamilton's method we still have some doubts about how this will behave in the user's hands. So we didn't want to have this hard-coded in Money class. We wanted to have it changeable whenever needed. We wanted to make our Value Object Opened for extension but Closed for modification. That's why RemainderDistribution is an interface. One of its possible implementations, the one we used, is HamiltonApportionmentDistribution:

public class HamiltonApportionmentDistribution implements RemainderDistribution {

  @Override
  public void distribute(List<Quota> quotas, long total) {
    long remain = total;
    for (Quota quota : quotas) {
      remain = remain - quota.getAmount();
    }
    List<Quota> sortedQuotas = quotas.stream().sorted(Comparator.comparing(Quota::getFractionalPart).reversed()).collect(Collectors.toList());
    Iterator<Quota> iterator = sortedQuotas.iterator();
    while(remain > 0) {
      remain = remain - 1;
      iterator.next().addRemain(1);
    }
  }

}

This way we solved that initial problem. where rounding down we lost 3 cents (remember that rounding down is due to the cents, similar to when we round a senator down). The calculation must be done using the smallest unit, in this case, cents. And we got this result:

#	Proportion	Gross Value	Gross Value in Cents	Final Value
1	22.9%	229.0458	22904.58	229.05
2	27.7%	277.0554	27705.54	277.05
3	7.8%	78.0156	7801.56	78.02
4	22.6%	226.0452	22604.52	226.04
5	19%	190.038	19003.80	190.04
Total	100%	1000.20	100020	1000.20

At this point I hope I have demystified the intersection between Alexander Hamilton, Martin Fowler and Uncle Bob with the Financial Systems. And, as bonus, you get some code to apply in your favorite language. Ah, all this code was covered with Unit Tests.

Bonus: if you don't know who Alexander Hamilton was, there is a musical movie available in Disney+, called Hamilton. It tells the story of this who was the American First Secretary of Treasury recorded with rap, hip hop and jazz, directly from the Broadway in 2016. Here's the trailer of this amazing film:

Spring Boot Development Environment with Docker and VS Code

Leandro Boeing Vieira — Mon, 03 May 2021 12:04:34 +0000

"It works on my machine."

If you're a developer, chances you've heard, and said, it at least once in your life are huge. There can be tons of reasons for that: your processor architecture, your operational system, your compiler version, may be different from your colleague's. Even worse scenario is when you deploy your applications in cloud environments and they crash. But how? It worked on my machine!

The old way

In a recent past, for Java projects - more specifically Spring Boot ones, I used to install sdkman and tried to arrange with the whole team to use the very same vendor and version of the JDK. Problem is, it depends on human actions to work. And humans can fail.

With that in mind, I'd like to introduce to you a whole new world: development of a Spring Boot application in Visual Studio Code and compile, test and run in a Docker container. I know you just turned up the nose about Java and VS Code, but trust me, it's gonna work and be worth it.

The new Era

So, no need for a JDK installed on your machine. But you'll need VS Code and Docker, of course. After you install them, open your VS Code. In the Extensions menu, search for "Remote - Containers" and install it:

Then, head to Spring Initializr, scaffold a new project, download and extract the files on your machine:

Remember to add Spring Web and Spring Boot DevTools.

Now, in your VS Code, open the Command Palette (usually Ctrl or Command + Shift + P) and type ">Remote-Containers: Open Folder in Container", select it and choose the location of your extracted Spring Boot application:

Now, it's time to configure your development environment container.

Select "Java - Develop Java applications":

Select your Java version, in my case, 11:

Select "Install Maven":

By now, your VS Code should have created a new folder in your project, called .devcontainer with a Dockerfile and devcontainer.json. You don't need to worry about them for now. Since this will be the first time your VS Code will run your application in a Docker container, it can take some time to download the images. Be patient. Once it is finished, you will be notified.

Select the Run menu, click on "Open a file" and navigate to your Main class, in my case HelloFromContainerApplication:

Now, if you click on the button "Run and Debug" it will run the application. Optionally, clicking on "No Configuration" and then "Add Configuration", VS Code will create a launch.json configuration file.

Finally, if you hit http://localhost:8080/ in your browser you will see that the application is up and running in Debug mode, perfect to install some breakpoints and start your awesome solution. And remember DevTools? Go ahead and add a new endpoint to your application. It will live-reload in the container as well.

Push config to Github?

Now comes the controversy part. Although it's recommended that you do not push specific IDE configuration files to your repository, I believe that if the whole team agrees to work in that manner, the .devcontainer could reside remotely. By doing this, you will mitigate the human failures and there will be no more "it works on my machine" excuses. Every environment, regardless of operational system, processor architecture or previous JDK installations, will behave similarly. This may even improve the speed of newcomers to the project for it will require less guidance and hit fewer issues related to environment setup.

Dockerfile for production environment

As a final hint, if you look closely to the Dockerfile created by VS Code inside .devcontainer folder, you will see a comment like:

// See here for image contents: https://github.com/microsoft/vscode-dev-containers/tree/v0.158.0/containers/java/.devcontainer/base.Dockerfile

This can be your guidance to creating your own Dockerfile, based on your local working environment. In this case, the Java image being used is the openjdk:11-jdk-buster and I would most likely want to use the same in production.

O que Softwares Financeiros, Martin Fowler, Uncle Bob e Alexander Hamilton têm em comum?

Leandro Boeing Vieira — Tue, 26 Jan 2021 14:10:02 +0000

Como disse Martin Fowler no livro Patterns of Enterprise Application Architecture:

"Uma boa parte dos computadores neste mundo manipula dinheiro, então sempre me intrigou que Money não seja um tipo de dados em qualquer linguagem de programação convencional."

Patterns of Enterprise Application Architecture sugere a implementação de uma classe Money, com atributos currency e amount, bem como um método allocate que recebe uma lista de proporções e distribui esse dinheiro sem perder valor com arredondamentos. Nesse artigo vou mostrar como implementamos nosso Money pra resolver um problema real de perda de centavos em rateio, bem como resolver o mistério do título.

Já tínhamos uma classe Money, o que facilitou muito na escrita do Money Pattern. Então se eu puder ter a pretensão de dar uma primeira dica é: não use Double ou BigDecimal pra valores financeiros. Construa seu Value Object. Depois de ter valores financeiros espalhados por todo seu sistema, vai ser bem difícil - mas não impossível - refatorar.

Nossa classe Money não tem o atributo currency pois não temos a necessidade de internacionalização, pelo menos não ainda. E não vamos ter implementação de currency enquanto não precisarmos de fato. Assim como também não tínhamos o método allocate. Até que precisamos. Portanto nosso Money era assim:

public class Money implements Serializable {

  private final BigDecimal amount;

  private Money(BigDecimal amount) {
    if (amount == null) {
      throw new AmountCantBeEmptyException();
    }
    this.amount = amount;
  }

  public static Money of(BigDecimal amount) {
    return new Money(amount);
  }

  public Money plus(Money addition) {
    return Money.of(this.amount.add(addition.amount));
  }

  public Money minus(Money discount) {
    return Money.of(this.amount.subtract(discount.amount));
  }

  public Money times(BigDecimal factor) {
    return Money.of(this.amount.multiply(factor));
  }

  public BigDecimal getAmount() {
    return amount;
  }

  @Override
  public boolean equals(Object obj) {
    if (obj == null || !(obj instanceof Money)) {
      return false;
    }
    return this.amount.compareTo(((Money) obj).amount) == 0;
  }

  @Override
  public int hashCode() {
    return this.amount.hashCode();
  }

}

Isso resolvia boa parte dos nossos problemas financeiros. Até que o fatídico dia em que precisamos do allocate chegou. Uma despesa de R$ 1000,20 deveria ser rateada entre várias contas da seguinte maneira:

Como podem perceber, se aplicarmos o percentual de proporção de rateio em cada item, nunca chegaremos em R$ 1000,20 - isso porque centavo é uma medida indivisível, então um valor financeiro representado por Money não pode ser R$ 229,0458 por exemplo. Se arredondarmos pra baixo, "perdemos" 3 centavos. Se arredondarmos pra cima, "ganhamos" 2 centavos. E note que mesmo usando o Round Half Even, perdemos precisão. Esse último é o modo de arredondamento comumente utilizado em sistemas financeiros, inclusive homologado pela ABNT através da norma NBR 5891.

E sabem quem enfrentou um problema parecido? Ele mesmo, George Washington, o primeiro presidente dos Estados Unidos, e uma das soluções propostas foi de Alexander Hamilton, que veio a ser o Primeiro Secretário do Tesouro dos EUA, e seu Largest Remainder Method.

O problema enfrentado por eles à época era resumidamente o seguinte, descrito no U.S. Census Bureau:

Um país com 4 estados, com diferentes populações em cada estado, e 20 assentos no Senado. Quantos senadores cada estado teria para que eles fossem representados proporcionalmente? Um senador, assim como um centavo, também não pode ser dividido em partes. Certo? Só pra confirmar aqui... =D

O método de Hamilton consiste em calcular a proporção da população total de 11882 pela quantidade de 20 assentos disponíveis chegando no divisor de 594,1. Agora pra cada estado divide-se sua população por esse divisor, por exemplo no estado 1 2560/594,1 chegando no quociente de 4,31.

Como já concordamos, não podemos ter 4 senadores e 0,31 de um senador para um estado. Então o número de senadores do estado 1 é 4, que é a parte inteira do resultado. E isso acontece para cada um dos outros resultados. Ao final, por conta dos arredondamentos da parte inteira, o total de senadores alocados nos estados é de 18. Pra quais estados vão os outros 2? É aí que Hamilton entra com uma possível solução. A proposta dele é que distribuamos esses 2 assentos para os estados que ficaram com a maior parte decimal antes do arredondamento.

Explico. Se suprimirmos a parte inteira da coluna Senadores por Estado e ordenarmos pela parte decimal, o resto, em ordem decrescente, ficaríamos com:

1,67
5,58
8,44
4,31

Como temos um total de 2 senadores pra redistribuir, os estados que recebem esses senadores são os 2 primeiros da lista. Resultando na coluna Senadores por estado após Método Hamilton.

Existe um paradoxo a se notar que foi descoberto ao aplicar o método Hamilton na população do Alabama, por isso também é chamado de Paradoxo do Alabama, que não será coberto aqui. Mas é onde entra o nosso querido Uncle Bob no artigo.

Entre suas inúmeras contribuições para a comunidade de desenvolvimento de software, Uncle Bob popularizou os princípios SOLID. Era relevante lá na década de 90, é relevante hoje. O princípio que iremos focar agora é o Open-Closed Principle.

Precisamos alterar nossa classe Money para comportar o método allocate pra conseguir distribuir seu valor em propoções sem perder centavos. Então criamos o seguinte método:

public class Money implements Serializable {
  private static final BigDecimal ONE_HUNDRED = new BigDecimal(100);

  public List<Money> allocate(List<BigDecimal> ratios, RemainderDistribution distribution) {
    long amountInCents = toCents();
    List<Quota> quotas = new ArrayList<>();
    for (BigDecimal ratio: ratios) {
      quotas.add(new Quota(amountInCents, ratio));
    }
    distribution.distribute(quotas, amountInCents);
    return quotas.stream().map(Quota::toMoney).collect(Collectors.toList());
  }

  public long toCents() {
    return this.amount.multiply(ONE_HUNDRED).longValue();
  }
}

public class Quota {
  private static final BigDecimal ONE_HUNDRED = new BigDecimal(100);

  private long amount;
  private long total;
  private BigDecimal ratio;

  public Quota(long total, BigDecimal ratio) {
    this.total = total;
    this.ratio = ratio;
    this.amount = ratio.multiply(BigDecimal.valueOf(total)).longValue();
  }
}

public interface RemainderDistribution {
  void distribute(List<Quota> quotas, long total);
}

Lembra do Paradoxo do Alabama? Mesmo tendo validado com nosso Product Manager que adotaríamos o método de Hamilton ainda temos dúvidas sobre quais consequências esse paradoxo, ou até outro, pode ter. Então não queríamos "chumbar" a distribuição no código do Money. Queríamos deixar nosso Value Object aberto para extensão mas fechado para modificação. Por isso RemainderDistribution é uma interface. Uma das suas implementações, a que utilizamos, é a HamiltonApportionmentDistribution.

public class HamiltonApportionmentDistribution implements RemainderDistribution {

  @Override
  public void distribute(List<Quota> quotas, long total) {
    long remain = total;
    for (Quota quota : quotas) {
      remain = remain - quota.getAmount();
    }
    List<Quota> sortedQuotas = quotas.stream().sorted(Comparator.comparing(Quota::getFractionalPart).reversed()).collect(Collectors.toList());
    Iterator<Quota> iterator = sortedQuotas.iterator();
    while(remain > 0) {
      remain = remain - 1;
      iterator.next().addRemain(1);
    }
  }

}

Dessa maneira resolvemos aquele problema inicial, onde arredondando pra baixo "perdíamos" 3 centavos (lembre-se que o arredondamento pra baixo é por conta dos centavos, similar a quando "arredondamos um senador" pra baixo). O cálculo deve ser feito utilizando a menor unidade de medida, ou seja, centavos. E chegamos no seguinte resultado:

Espero que até aqui eu tenha desmistificado a intersecção entre Alexander Hamilton, Martin Fowler e Uncle Bob com os sistemas financeiros. E, de quebra, você ganha uns códigos pra poder aplicar na sua linguagem favorita. Ah, todo esse código foi coberto por testes unitários. E sabe quando você leu as sentenças na primeira pessoa do plural? É porque desenvolvemos essa solução em 3, então todo o crédito também ao Victor Sales de Brito e Lucelia Siqueira. Valeu, time!

Bônus: pra saber quem foi Alexander Hamilton, existe um musical disponível na Disney+, chamado Hamilton. Conta a história desse que foi o Primeiro Secretário do Tesouro Americano em forma de rap, hip hop e jazz, gravado diretamente da Broadway em 2016. Segue trailer desse musical fantástico:

Introduction - A bot responding to a recruiter via Telegram using Watson Assistant's Natural Language Processing

Leandro Boeing Vieira — Sun, 20 Sep 2020 20:07:00 +0000

I believe that naming articles is as difficult as naming variables and classes, but let's go. For now, that'll do. Although large, it seems significant enough to demonstrate what I intend to cover in this series.

As you may have seen in my LinkedIn post https://www.linkedin.com/posts/leandro-boeing-vieira_tdd-springboot-java-activity-6712687112602349568-FhoD, I will "teach" (how much pretension) how to train a bot to respond to recruiters, making decisions for me, using the good principles of a clean architecture to separate the logic of my business from the necessary infrastructure for that.

Ok, but what are my business rules? Respond to a recruiter based on the context of the conversation. And what is the infra? Telegram API, Watson Assistant, REST etc. You'll see below a drawing of the initial architecture. Of course, it may change until the end of the project, but whenever it happens, I will tell you what has changed.

I was surprised that an architecture for such a cool theme is as simple as that. I finished drawing and thought: something must be missing. But in fact, it has served me well so far. Some points to highlight in relation to the stack I use to implement this architecture:

Telegram itself indicates some unofficial SDKs for developers at https://core.telegram.org/bots/samples.
I decided to use the Java Telegram Bot API (https://github.com/pengrad/java-telegram-bot-api) because it suited me well and I liked the support on github, answering a question in less than 24 hrs.
This implementation of the telegram API provides a much better Webhook mechanism than polling the server for a possible new message. With that, I end up being "nice" with Heroku too, as my application can shut down after 30 minutes of inactivity. With the polling solution, the application receives a POST every X seconds and it never sleeps.
Currently, the application does not yet have the "Take decision based on context" logic developed within the Use Case "Answer Recruiter". I mean, we will develop together. Nice right?! But it already communicates with IBM Watson Assistant and returns the context I need for the bot to be able to answer at least the initial greeting.
I have a minimum logging for development level so I can analyze what the user is sending and what he is receiving as a response. As the application sleeps from time to time (characteristic of Heroku) I always lose these logs. If anyone has a cool idea on how to persist these logs for free, I would appreciate it very much!

It is worth noting that, in an initial idea, I will not "teach" how to create an instance of IBM's Watson Assistant. There is a very complete material at: https://cloud.ibm.com/docs/assistant?topic=assistant-getting-startedodos. But I will show you how I created the dialog nodes, the intents and the entities related to the domain of my application. I think it makes more sense that way.

I'm also not going to teach you how to create a bot on Telegram. It is VERY simple and they teach here: https://core.telegram.org/bots#3- how-do-i-create-a-bot.

That's it for now. We haven't entered "show me the code" yet, but be patient. I thought this introduction is important for us to give a cool rhythm in this series, without too much information at once. I also think it is important that you have a first contact with the architecture, become familiar with it, before looking at the implementation decisions soon.