DEV Community: Thiago Henrique Domingues

Pare de ignorar as janelas quebradas do seu código! Veja por que pequenos descuidos viram grandes problemas

Thiago Henrique Domingues — Thu, 03 Jul 2025 23:23:10 +0000

Você conhece o paradoxo da janela quebrada? Esta é uma metáfora usada na criminologia que diz que, se uma janela de um edifício for quebrada e não receber reparo logo, a tendência é que as pessoas passem a vandalizar as demais janelas, até que todo o edifício esteja destruído. Apesar de a teoria ter nascido na criminologia, ela pode ser aplicada a várias áreas, inclusive o desenvolvimento de software.

Se você trabalha em um projeto com decisões de design ruins, a tendência é continuar replicando os mesmos erros. A cada novo commit, o sistema não muda muito individualmente, mas com o tempo, a tendência é que o design do código vai se desgastando cada vez mais até erodir completamente.

Por isso, é importante policiar os detalhes e dedicar tempo e esforço para manter a alta qualidade do design de código. Isso inclui refatorações constantes, escrever uma boa documentação, escrever bons testes automatizados e mais. Eu entendo que, com a correria do dia a dia, nem sempre isso é possível, mas, como desenvolvedor, é o nosso dever de "consertar as janelas quebradas" do projeto.

Referências

Coding Horror. The Broken Window Theory. Disponível em: https://blog.codinghorror.com/the-broken-window-theory/.

Mat Ryer. Broken Windows Theory: Why Code Quality and Simplistic Design Are Non-Negotiable. Medium, 2017. Disponível em: https://medium.com/@matryer/broken-windows-theory-why-code-quality-and-simplistic-design-are-non-negotiable-e37f8ce23dab.

Problems details: A importância de mensagens de erro claras e estruturadas na sua API REST

Thiago Henrique Domingues — Wed, 02 Jul 2025 12:51:17 +0000

Se você já precisou integrar sua aplicação com APIs externas, com certeza enfrentou a dificuldade de lidar com diferentes formatos de erros. Ter mensagens de erro bem estruturadas é tão importante quanto ou até mais do que retornar respostas de sucesso bem definidas.

É bastante comum cada projeto definir seu próprio padrão de retorno de erros. Em sistemas pequenos, isso pode funcionar bem, mas à medida que o número de integrações cresce, a complexidade no tratamento de exceções cresce junto. Imagine um projeto que precisa integrar com diversas APIs diferentes, e cada uma delas possui um padrão de erro diferente. Agora pense no tempo que os desenvolvedores vão gastar apenas para entender e tratar cada formato antes de resolver o problema real.

Como forma de resolver esse problema, a Internet Engineering Task Force (IETF) propôs o padrão Problem Details para retorno de erros em APIs. Ele define uma estrutura padronizada e consistente para respostas de erro, garantindo que os consumidores consigam entender e tratar falhas de forma mais simples e clara. Em vez de cada desenvolvedor ter que reinventar a roda, eles podem usar esse padrão para definir os detalhes de cada solicitação.

A estrutura do objeto Problem Details encapsula informações de erro de uma forma que pode ser universalmente compreendida em diferentes sistemas e tecnologias.

type: URI que identifica o tipo de problema;
status: Código HTTP;
title: resumo legível do erro;
detail: explicação detalhada;
instance: URI específica do erro ocorrido (opcional);
extensions: qualquer campo que adiciona informações adicionais ou contexto para o cliente que está consumindo;

Segue um exemplo de um objeto resposta que contém a propriedade de extensão errors:

{
  "type": "https://myapi.com/errors/invalid-input",
  "title": "Invalid input data",
  "status": 400,
  "detail": "One or more fields have invalid data.",
  "instance": "/users",
  "errors": {
    "email": ["The email field must be a valid email address."],
    "password": [
      "The password must be at least 8 characters long.",
      "The password must contain at least one number."
    ]
  }
}

Problemas são inevitáveis em qualquer sistema, mas retornar erros bem estruturados pode facilitar a vida de quem está consumindo seu serviço mais fácil!

Referências

Zuplo. The Power of Problem Details. Disponível em: https://zuplo.com/blog/2023/04/11/the-power-of-problem-details.
Swagger. Problem Details RFC9457: Doing API Errors Well. Disponível em: https://swagger.io/blog/problem-details-rfc9457-doing-api-errors-well/#references.
IETF. RFC 7807 - Problem Details for HTTP APIs. Disponível em: https://datatracker.ietf.org/doc/html/rfc7807.

Sem clareza nos requisitos, nem o melhor código salva o projeto

Thiago Henrique Domingues — Wed, 11 Jun 2025 15:08:54 +0000

É muito comum, especialmente no início da carreira, focarmos exclusivamente na escrita de código e acabarmos negligenciando uma das etapas mais críticas de um projeto: entender o que realmente precisa ser construído.

Não adianta nada ter um sistema com a melhor arquitetura, escrito na linguagem mais moderna, com alta cobertura de testes, se ele não atender às necessidades reais de seus usuários, de nada vale.

A engenharia de requisitos existe justamente para isso, trazer clareza, alinhamento e previsibilidade ao desenvolvimento. Ignorar essa fase pode comprometer completamente o resultado final.

Problemas na definição de requisitos têm um alto custo e podem gerar uma série de consequências, como retrabalho constante, entregas incompletas e até implementação de funcionalidades desnecessárias. Que no fim têm o risco de entregar um sistema que vai ser rejeitado pelos usuários, uma vez que não resolve seus problemas.

Investir tempo em entender bem o problema antes de pensar na solução não é perda de tempo. Pelo contrário: é uma das formas mais eficazes de garantir que o projeto siga na direção certa desde o início!

Brag Document: o hábito que pode transformar sua carreira

Thiago Henrique Domingues — Fri, 30 May 2025 21:00:52 +0000

A gente cresce ouvindo que, se fizermos um bom trabalho as pessoas vão perceber e recompensar por isso. Mas a real é que o ambiente corporativo é um pouco mais complexo que isso.

Quantas vezes você já entregou algo incrível, ajudou o time, resolveu um problema... e nada aconteceu? Muitas vezes, nossas entregas acabam passando despercebidas por nossa liderança, não por maldade, mas porque todo mundo está ocupado demais com suas próprias entregas.

A melhor forma de evitar que seu trabalho passe despercebido é mantendo um registro das suas contribuições e conquistas. Esse é justamente o propósito do Brag Document, também conhecido como Hype Document.

O termo foi popularizado pela engenheira Julia Evans no artigo "Get your work recognized: write a brag document"
publicado em seu blog. Em tradução livre, “Brag Document” significa algo como “documento de ostentação”. Mas, apesar do nome, a ideia não é se gabar, e sim garantir que o seu trabalho seja reconhecido. Afinal, se nem você acompanha o impacto do que faz, como esperar que os outros percebam?

À primeira vista, o nome pode soar estranho, mas a ideia por trás do Brag Document é bastante simples: ele nada mais é do que um registro das atividades e conquistas das quais você se orgulha.

Você pode fazer isso em um documento de texto, uma planilha ou até mesmo um bloco de notas, basicamente o formato não importa. O essencial é manter esse hábito com regularidade. Tenta atualizar semanalmente ou, no máximo a cada quinze dias. Assim, você registra tudo enquanto ainda está fresco na memória e não corre o risco de esquecer nada importante.

No fim das contas, o Brag Document não é sobre se gabar. É sobre construir uma narrativa clara do seu impacto, e não deixar que suas contribuições se percam no corre do dia a dia. Seu crescimento profissional também depende disso.

Referências

Entendendo conceitos da Arquitetura limpa

Thiago Henrique Domingues — Wed, 11 Oct 2023 02:14:27 +0000

Tabela de Conteúdo

Prólogo
Camadas
- Entidades
- Casos de uso
- Adaptadores de interface
- Framework e drivers
Conclusão
Referências

Prólogo

Já faz algum tempo que venho me aventurando estudando um pouco mais sobre arquitetura e design de software, e recentemente acabei me esbarrando no conceito de Arquitetura Limpa.

Esse padrão foi proposto por Robert C. Martin (Uncle Bob) em uma postagem em seu blog em agosto de 2012. Este padrão tem como objetivo separar o software em camadas, onde quanto mais interno, maior é o nível do software.

Essa arquitetura tem como objetivo produzir sistemas que são:

Independência de frameworks: a arquitetura não depende da existência de nenhuma biblioteca externa. Isso permite que você use os frameworks como ferramentas em de vez de ser obrigado a adaptar seu sistema a ele;
Testabilidade: as regras de negócio podem ser testadas sem a UI, banco de dados ou qualquer outro elemento externo;
Independência de UI: A UI pode mudar sem afetar o resto do sistema. Uma UI web pode ser substituída, por uma de console por exemplo.
Independência de banco de dados: Você pode trocar o MySql por Mongo por exemplo sem afetar as regras de negócios;
Independência de fatores externos: Suas regras de negócios não sabem nada sobre as interfaces do mundo externo.

Camadas

O diagrama acima é uma representação da arquitetura limpa criado pelo próprio autor. Por padrão o autor divide o sistema em quatro camadas: Entidades, Casos de uso, Adaptadores de interface e Frameworks e drivers. Quanto mais interno, maior é o nível do software. Os círculos mais externos são mecanismos. Os círculos mais internos são políticas.

A principal regra desse padrão é a Regra da Dependência. Essa regra diz que as dependências do código só podem apontar para dentro. Um círculo interno não pode saber qualquer coisa sobre algo em um círculo externo.

Geralmente resolvemos essa aparente contradição usando o Princípio de Inversão de Dependência. Em uma linguagem orientada a objetos como o Java, por exemplo.Podemos utilizar interfaces e relacionamentos de herança de modo que as dependências do código-fonte se oponham ao fluxo de controle.

Entidades

No círculo mais interno temos as entidades. As entidades são responsáveis por manter toda a regra de negócio da aplicação. Mas afinal, o que é uma regra de negócio? Robert Martin define regras de negócio como:

Regras de negócio são regras e procedimentos que geram ou economizam dinheiro para a empresa. [..] Podem gerar ou economizar dinheiro mesmo se forem executadas manualmente.

Vale destacar o último trecho da explicação no qual o autor menciona que uma regra de negócio pode gerar ou economizar dinheiro mesmo se forem executadas de forma manual. Por exemplo, um banco cobrar N% de juros por um empréstimo é uma regra de negócio, visto que não importa se essa informação é calculada pelo computador ou por uma caixa com um ábaco. Chamaremos essas regras de Regras Cruciais de Negócio.

As regras de negócio normalmente exigem alguns dados para trabalhar. Por exemplo, continuando com o exemplo anterior, para realizar um empréstimo precisamos de um saldo, uma taxa de juros e um cronograma de pagamentos. Chamaremos essas informações de** Dados Cruciais de Negócio**. Esses dados existiriam mesmo se o sistema não fosse automatizado.

Juntando as **Regras Cruciais de Negócio **e os **Dados Cruciais de Negócio **conseguimos construir a nossa entidade Empréstimo. Uma entidade é um objeto contido em nosso sistema. Ela incorpora um pequeno conjunto de regras cruciais de negócio que operam em cima dos dados cruciais de negócios.

Quando criamos esse tipo de classe, estamos reunindo o software que implementa um conceito crucial para o negócio onde estamos separando esse software de todas as outras questões do sistema automatizado que estamos construindo. A entidade é puro negócio e nada mais,

Importante ressaltar que não é necessário uma linguagem orientada a objetos para se implementar uma entidade. Basta que você reúna os dados e as regras cruciais do negócio em um módulo único e separado do restante do sistema.

Casos de uso

Ao contrário das regras de negócio que são puras e podem ser executadas manualmente, os casos de uso não seriam executadas em um ambiente manual visto que só fazem sentido para sistemas automatizados. Segundo Robert Martin um caso de uso é:

Caso de uso é uma descrição da maneira como um sistema automatizado é usado. Ele especifica a entrada e a a ser fornecida pelo usuário, a saída retornada e os passos de processamento envolvidos na produção dessa saída.

Casos de usos são nada mais nada menos que objetos com métodos que implementam as regras de negócio da aplicação, além de um conjunto de dados que serão manipulados e as referência para as Entidades com as quais interage. Em suma, os casos de uso especifica como e quando as Regras Cruciais de Negócios dentro das entidades serão invocadas.

Exemplo de casos de uso

A figura acima representa um exemplo de caso de uso de uma aplicação usada por bancários para criar um novo empréstimo. Por determinação do banco, para oferecer um empréstimo para um cliente é necessário validar seus dados além que sua pontuação de crédito deve ser superior a 500 pontos. Com isso o banco pode determinar que o sistema não proceda com a tela de estimativa de pagamento até que a tela de informações pessoais seja preenchida e verificada.

Adaptadores de interface

Adaptadores de interface funcionam como adaptadores de tomadas

Esta camada é composta por um conjunto de adaptadores de interface que convertem dados no formato que é mais conveniente para os casos de uso e entidades, para o formato mais conveniente para algum agente externo como a base de dados ou a web.

Framework e drivers

Frameworks web estão localizados nesta camada

Conclusão

Ao separar o software em camadas e obedecer a regra da dependência a aplicação criada será altamente testável e de fácil manutenção, visto que quando uma das partes externas se tornar obsoleta, como a base de dados é substituir por outro atualizado com o mínimo de esforço.

Referências

Blog Clean Coder https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html
Livro Arquitetura limpa: O guia do artesão para estrutura e design de software