DEV Community: Leandro Boeing Vieira

Repository Harness, Part 2: 30 Runs Later, It Wasn’t Cheaper. It Was More Predictable.

Leandro Boeing Vieira — Mon, 20 Jul 2026 19:24:35 +0000

This is the follow-up to Coding Agents Evolved. Our Repositories Didn’t..

My first Repository Harness benchmark produced an uncomfortable result.

The Harness completed the task faster than a monolithic AGENTS.md, but it used more fresh input tokens.

That could have meant the idea was wrong.

It could also have meant that my first implementation of progressive disclosure was not strict enough.

So I changed the routing model, rebuilt the benchmark baseline, and ran the experiment again.

This time, I ran 30 measured executions.

The result was not a dramatic reduction in token usage.

It was something more useful:

The Repository Harness made the agent’s behavior substantially more predictable.

The idea

Most repositories expose their knowledge through a mix of:

README files;
architecture documents;
contribution guides;
scripts;
tribal knowledge;
one increasingly large AGENTS.md.

A monolithic instruction file works, but every task receives the complete repository handbook, even when most of it is irrelevant.

The Repository Harness replaces that model with a small entry point and routed context:

AGENTS.md
    ↓
.harness/
├── harness.yaml
├── project-specific guidance
├── engineering guidance
└── asset guidance

The root file explains how to use the Harness.

The manifest classifies the task and selects the repository guidance required for that task.

The original hypothesis was:

Selective context routing should preserve implementation quality while reducing unnecessary context.

The first benchmark did not prove that.

What changed in version 2

The first Harness used broad loading rules such as:

load_when:
  - implementation
  - feature
  - validation

Those labels were too general.

Almost every coding task is an implementation. Many tasks are features. Every completed task needs validation.

The agent therefore had a reasonable incentive to load most of the documentation.

I had modularized the repository knowledge.

I had not created strict routing.

The second version added:

repository-defined concerns;
directory scopes;
required and optional context;
escalation rules;
context budgets;
route-specific validation.

Before explaining how that routing behaved, it helps to understand the repository used in the experiment.

The benchmark project

The benchmark used a real game project built with Godot and C#.

The task was a gameplay-input change involving camera controls.

The agent needed to:

move gamepad zoom from the triggers to the vertical right-stick axis;
preserve horizontal right-stick rotation;
preserve mouse-wheel zoom;
add horizontal mouse movement rotation;
update relevant prompts and tests;
avoid breaking gameplay and menus.

This repository was useful for the experiment because it contained different kinds of knowledge:

Godot and gameplay conventions
general engineering rules
asset rules
validation commands

A camera-input task should need the Godot-specific guidance.

It should not need asset guidance.

It should only need broader engineering guidance if the implementation crosses an architectural boundary.

That made the task a practical test of selective routing.

The two variants

I created two isolated versions of the same repository.

Monolithic variant

AGENTS.md

All repository guidance lived in one concise root document.

Harness variant

AGENTS.md
.harness/

The root file acted as an entry point.

The Harness contained:

.harness/
├── harness.yaml
├── GODOT.md
├── ENGINEERING.md
└── ASSETS.md

For this camera-input task, the expected route was:

AGENTS.md
+ .harness/harness.yaml
+ .harness/GODOT.md

Across all 15 measured Harness runs, the agent inspected the manifest and the Godot-specific guidance without loading the unrelated engineering or asset documents.

That confirmed that the routing mechanism itself was working.

The remaining question was whether it improved the complete execution.

Benchmark design

Both variants used the same:

coding agent;
model;
source-code baseline;
implementation prompt;
test suite;
acceptance criteria.

I ran:

3 warm-ups per variant
15 measured runs per variant
30 measured runs total

The order alternated between variants.

The prompt was identical in every run.

Each repository started from a clean, frozen commit.

Every measured execution satisfied the benchmark acceptance criteria.

AGENTS:  15/15 accepted
HARNESS: 15/15 accepted

The Harness did not reduce reliability.

The average results were almost tied

Metric	AGENTS	Harness	Harness difference
Duration	188.36 s	185.61 s	-1.46%
Total input tokens	803,295	829,006	+3.20%
Uncached input tokens	63,147	61,859	-2.04%
Output tokens	5,947	5,630	-5.32%
Reasoning tokens	987	952	-3.63%
Commands	14.40	14.53	+0.93%
Failed commands	6.07	7.00	+15.38%
Changed files	6.20	6.00	-3.23%

The Harness was slightly faster.

It used slightly fewer uncached input tokens and produced less output.

It also used more total input tokens and executed more failed commands.

None of those mean differences was large enough to justify a strong claim that the Harness was reliably faster or cheaper.

The honest conclusion is:

Average efficiency was approximately tied.

That was not the most important result.

The routed context was only modestly smaller

The concise monolithic AGENTS.md was roughly 14 KB.

The Harness route loaded about:

small AGENTS.md       ~0.8 KB
harness.yaml          ~3.3 KB
GODOT.md              ~7.3 KB
--------------------------------
routed context       ~11.5 KB

The Harness successfully avoided unrelated documents, but the direct reduction was only a few kilobytes.

That is small compared with a complete agent execution containing source files, search results, command output, tests, diffs, and repeated tool context.

The experiment averaged roughly 62,000 uncached input tokens per run.

Saving a few kilobytes of instructions was unlikely to transform the total.

This changed the main question.

The Harness may not primarily optimize the size of the initial prompt.

It may optimize how consistently the agent navigates the rest of the task.

The strongest result was lower variance

Metric	AGENTS standard deviation	Harness standard deviation	Reduction
Duration	46.67 s	25.10 s	46.2%
Total input tokens	239,991	108,745	54.7%
Uncached input tokens	19,211	9,855	48.7%
Output tokens	1,430	772	46.0%
Commands	3.27	1.13	65.6%

In this sample, the Harness produced:

46% less variation in duration;
55% less variation in total input;
49% less variation in uncached input;
46% less variation in output;
66% less variation in command count.

I did not begin this project with variance as the primary hypothesis.

But predictability may matter more than a small improvement in the mean.

Lower variance improves:

cost forecasting;
CI capacity planning;
timeout configuration;
rate-limit management;
anomaly detection;
user expectations.

The Harness did not make every run dramatically cheaper.

It made the execution path more repeatable.

What selective routing appears to change

A monolithic instruction file gives the agent every repository rule at once.

The agent must decide which ones matter while already performing the task.

A routed Harness makes the selection explicit:

task classification
        ↓
repository route
        ↓
required context
        ↓
optional escalation
        ↓
selected validation

This does more than organize Markdown files.

It constrains the agent’s decision space.

That provides a plausible explanation for the lower variance, although this benchmark cannot prove causation.

The strongest conclusion supported by the data is:

Repository-defined routing preserved implementation success and made coding-agent behavior more consistent.

Did the Harness win?

Not in the simple way I originally imagined.

The experiment does not prove that the Harness always uses fewer tokens or is reliably faster.

It does show that:

selective routing worked;
unrelated documents were not loaded;
implementation reliability was preserved;
average efficiency remained close to the monolithic version;
execution variability was substantially lower.

So the result is not:

The Harness is cheaper.

It is:

The Harness is more predictable.

That may be the more valuable engineering property.

The next experiment should be full-stack

The current benchmark tested one task inside one Godot repository.

The next step should test whether the routing model generalizes to a repository with clearly different technical domains.

A backend-and-frontend project is a stronger test because it contains knowledge that should not be loaded for every task:

backend
database
API contracts
frontend
accessibility
design system
integration tests
deployment

The next benchmark should include:

a backend-only task;
a frontend-only task;
a cross-stack task.

A useful Harness should remain narrow for isolated work and expand only when the task crosses a boundary.

A practical setup would be a TypeScript monorepo:

apps/
├── api/
└── web/

packages/
├── contracts/
└── testing/

Validation could be fully automated:

lint
type-check
unit tests
integration tests
production build
headless end-to-end tests

The next benchmark should measure not only tokens and duration, but also:

documents loaded;
unnecessary documents loaded;
route escalations;
changed-file scope;
p95 duration;
variance.

The central question for Part 3 is:

Can repository-defined routing stay narrow for backend-only and frontend-only work, then expand correctly for a cross-stack task?

Why memory should come later

Persistent memory is promising.

A Harness could eventually learn architectural decisions, recurring failures, conventions, validation paths, and known issues.

But adding memory now would mix two different hypotheses:

Does static routing generalize?
Does accumulated experience improve future tasks?

Memory also makes later runs depend on earlier ones, which complicates a controlled comparison.

The cleaner sequence is:

Part 2
Selective routing and predictability

Part 3
Full-stack generalization

Part 4
Lifecycle hooks and persistent memory

If the Harness generalizes in Part 3, memory becomes the next logical layer.

The project is not a failure

The original promise was token reduction.

The second benchmark did not produce a large or statistically conclusive reduction in average token use.

Instead, it revealed a different benefit:

Repository-defined context routing can make coding-agent behavior more predictable without reducing implementation success.

Reliable agent workflows need more than correct final code.

They need bounded behavior:

bounded context;
bounded validation;
bounded tool use;
explainable escalation;
repeatable execution paths.

That is what the Repository Harness is becoming.

The first article proposed the idea.

The first benchmark exposed a routing flaw.

The second benchmark showed that stricter routing worked and made the agent more consistent.

Part 3 will test whether that result generalizes beyond Godot.

The question is no longer only:

Can a Harness reduce tokens?

It is:

Can a repository define a predictable, auditable, and progressively disclosed operating environment for any coding agent?

The project is available at:

Repository Harness Specification

https://github.com/Repository-Harness-Specification

Coding Agents Evolved. Our Repositories Didn’t.

Leandro Boeing Vieira — Fri, 17 Jul 2026 15:23:00 +0000

Why giant AGENTS.md files may be wasting context, hurting maintainability, and making AI-assisted development harder to scale.

A few years ago, for many developers, using AI for software development meant copying a small piece of code into a chat window.

We would ask for a refactoring, copy the response back into the editor, run the tests ourselves, and return to the chat when something failed.

Coding agents changed that workflow.

Tools such as Codex, Claude Code, and others can now explore an entire repository, modify multiple files, execute commands, run tests, and iterate on failures.

Coding agents turned code assistants into tools capable of executing multi-step software development tasks.

But most repositories were not designed for this new kind of contributor.

The repository became part of the agent's working context

A coding agent needs much more than source code.

It may need to understand:

the project architecture;
dependency boundaries;
coding conventions;
test strategy;
build commands;
local environment requirements;
validation steps;
security restrictions;
the definition of done.

A common solution is to place these instructions inside files such as AGENTS.md, CLAUDE.md, or other agent-specific configuration files.

This works.

I have been doing something similar in my own projects for a while.

But as the repository grows, the instruction file grows with it.

Eventually, a single file may contain thousands of lines covering unrelated concerns:

Architecture
Testing
Environment setup
Coding standards
Infrastructure
UI conventions
Validation
Release workflows
Definition of done

At that point, the file is no longer just a set of agent instructions.

It has become an informal repository operating manual.

The monolithic context problem

A large AGENTS.md has an obvious advantage: the agent knows where to find it.

But it also creates several problems.

It is difficult for humans to navigate

These files are not only for agents.

Developers also need to read, review, maintain, and discuss the rules.

Someone changing a test should not need to navigate through multiplayer architecture, asset conventions, deployment rules, and UI standards.

Unrelated context may be loaded

A small bug in a domain class may not require information about:

production deployment;
UI assets;
database migrations;
release procedures;
external integrations.

When a large root instruction file is injected into every task, unrelated guidance may consume context that could otherwise be used for the task, the code, and the relevant documentation.

Different knowledge changes at different speeds

Architecture rules may remain stable for months.

Bootstrap commands may change after a toolchain update.

Validation rules may evolve every week.

Keeping all of them in one document makes ownership and maintenance harder.

The file becomes difficult to validate

A giant Markdown document is mostly passive guidance.

It may describe commands that no longer work, paths that no longer exist, or rules that contradict the current codebase.

This problem is not entirely theoretical.

OpenAI has publicly described moving away from a large AGENTS.md file because it consumed context, became difficult to maintain, and was hard to validate mechanically.

Their solution was to use a shorter AGENTS.md as a table of contents for a structured repository knowledge base.

That experience supports the direction of this experiment, but it leaves an important question open:

Can this approach become a vendor-neutral, reusable, and measurable repository specification?

A repository harness

I agree with the direction OpenAI has described: AGENTS.md should not contain the repository's entire operating model.

It should act as an entry point, while the detailed knowledge lives in a modular and versioned repository structure.

A small bootloader.

The actual repository knowledge could live in a versioned and modular structure:

AGENTS.md
    ↓
.harness/
├── architecture
├── environment
├── validation
├── workflows
└── manifest

The .harness directory is a proposed convention, not something coding agents currently understand automatically.

In the first version, AGENTS.md would remain the supported entry point and instruct the agent how to discover and use the repository harness.

The exact filenames are intentionally undefined at this stage.

For example, testing could be part of validation in a small project:

validation/
└── testing rules and commands

A larger project might need a dedicated testing document containing:

when to use unit tests;
when to use integration tests;
how to run each suite;
mocking and fake conventions;
test naming standards;
patterns for writing new tests.

The goal is not to force every repository into the same directory tree.

The goal is to define capabilities that agents can discover.

Progressive disclosure of repository context

With a modular harness, an agent working on a domain bug might load:

Architecture
Testing
Validation

An agent preparing the project for the first time might load:

Bootstrap
Environment
Validation

A task involving deployment might load an entirely different set.

This creates a form of progressive context loading:

Provide the agent with the context required for the current task, rather than the entire repository handbook.

The approach could potentially improve:

context efficiency;
token usage;
instruction discoverability;
human readability;
documentation ownership;
consistency between different coding agents.

But this is still a hypothesis.

Documentation is not enough

A useful repository harness should not consist only of Markdown files.

Whenever possible, instructions should point to executable and reproducible operations.

Instead of documenting a long sequence of test commands, the repository could expose:

./scripts/test-unit
./scripts/test-integration
./scripts/validate

The Markdown explains:

when the command must be used;
what it validates;
what failure means;
which exceptions are allowed.

The script defines how the operation is performed.

This also makes the repository easier to validate through CI and less dependent on an agent correctly reproducing a sequence of commands.

Beyond implementation tasks

The same concept could eventually apply before coding begins.

A team using Jira, GitHub Issues, Linear, Azure DevOps, another issue tracker, or an internal product backlog might define a repository-specific Definition of Ready.

Before a task enters the implementation pipeline, an agent could verify whether:

acceptance criteria are clear;
required architectural context exists;
dependencies are identified;
the task conflicts with existing documentation;
expected validation is defined;
important information is missing.

The team could also encode its agreed Definition of Done in the repository harness before implementation begins.

During and after implementation, the agent could use that definition to determine which tests, validations, reviews, documentation updates, and manual checks are required before considering the task complete.

The experiment

I am starting an open project called Repository Harness Specification.

The first goal is to compare two versions of the same repository:

Monolithic

AGENTS.md

All instructions are contained in one large file.

Modular

AGENTS.md
.harness/

The same information is organized into task-relevant modules that the agent can discover and load as needed.

I plan to evaluate both approaches using the same:

coding agent;
model;
repository;
starting commit;
implementation task;
validation criteria.

The experiment will measure more than token consumption.

Possible metrics include:

input tokens, when exposed by the selected agent or runtime;
cached and uncached input tokens, when available;
task success rate;
tests passed;
validation failures;
files changed outside the expected scope;
number of correction cycles;
execution time.

Reducing tokens is not useful if the agent produces worse code.

The real objective is to determine whether modular repository context can improve efficiency without reducing implementation quality.

Building it in public

The project will be developed publicly.

The next steps include:

defining the minimum repository harness;
migrating a real project manually;
creating reproducible benchmark tasks;
comparing monolithic and modular context;
publishing the results;
building a CLI to initialize and validate repository harnesses;
exploring integrations with different coding agents.

The structure presented in this article is not the final specification.

It is the first experiment.

Coding agents are evolving quickly.

Now we need to understand how repositories should evolve with them.

The project is available at:

Repository Harness Specification

https://github.com/Repository-Harness-Specification

Feedback, criticism, and contributions are welcome.

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.