标签：#cleancode

LIA is a hyperlocal employability platform I'm building for an isolated coastal district in Brazil — think fixed retail jobs, gigs, and a reputation layer, all matched by proximity instead of routed through a national job board. This post is about the implementation: the actual folder structure, the real RegisterUserUseCase, and the Argon2id decision — pulled straight from the repository, not reconstructed from memory. The Clean Architecture folder structure LIA's backend is organized in four layers, and the direction of dependency is non-negotiable: outer layers depend on inner layers, never the other way around. backend/src/ ├── domain/ │ ├── entities/ │ └── repositories/ # interfaces only ├── application/ │ ├── dto/ │ └── use-cases/ ├── infrastructure/ │ ├── database/ │ └── repositories/ # Prisma implementations ├── presentation/ │ ├── controllers/ │ └── routes/ └── shared/ └── errors/ Let's walk through the registration feature end to end, following that exact order. Domain — the entity and the repository contract The User entity is a plain interface. No decorators, no ORM annotations, no framework leaking in: typescript// domain/entities/user.ts export interface User { id: string; name: string; email: string; password: string; createdAt: Date; updatedAt: Date; } The repository is defined as a contract, not an implementation. The domain doesn't know — and doesn't care — whether it's backed by PostgreSQL, an in-memory map, or something else entirely: typescript// domain/repositories/user.repository.ts import { RegisterUserDTO } from '../../application/dto/register-user.dto.js'; export interface UserRepository { create(data: RegisterUserDTO): Promise<{ id: string; name: string; email: string; createdAt: Date; updatedAt: Date; }>; findByEmail(email: string): Promise<{ id: string; name: string; email: string; password: string; createdAt: Date; updatedAt: Date; } | null>; } Notice create() never returns the password hash. That's not an accident — it's the same "strip

The Quest Begins (The "Why") I still remember the first time I tried to track down a bug that only showed up after midnight. I opened my terminal, typed git log , and was greeted by a wall of commits that read like a toddler’s grocery list: * 7a9c3f1 (HEAD -> main ) fix stuff * 4b2e8a1 update * f1d9c6b wip * 9e3b7d2 more changes * … I spent three hours chasing a regression that turned out to be a one‑line typo in a file I hadn’t touched in weeks. The commit messages gave me zero clues, and the diff was a tangled mess of unrelated changes. I felt like I was wandering through a dungeon without a map, hoping the next room would hold the answer. That night I realized the real monster wasn’t the bug—it was the way I was committing code. My commits were large, vague, and scattered , making every subsequent step (review, revert, bisect) a gamble. If I wanted to keep my sanity (and maybe even enjoy coding again), I needed a better system. The Revelation (The Insight) The turning point came when I read about Conventional Commits —a lightweight convention that gives each commit a clear type ( feat , fix , docs , refactor , test , chore , etc.) and a short, descriptive message. It sounded simple, but the impact was massive: Atomicity – each commit does one thing. Clarity – the message tells you why the change exists, not just what changed. Automation – tools can generate changelogs, version bumps, and even release notes straight from the log. Adopting this felt like discovering a hidden shortcut in a Zelda dungeon—suddenly the whole map made sense, and I could sprint to the boss room with confidence. Wielding the Power (Code & Examples) Before – The Chaos Imagine we’re building a tiny API for user profiles. Here’s what a typical day of committing looked like (messages only, but the diffs were just as messy): $ git log --oneline -5 7a9c3f1 ( HEAD -> main ) fix stuff 4b2e8a1 update profile handler f1d9c6b wip 9e3b7d2 added auth middleware c5d4e3f refactor utils If I needed to ro

We've all been here. A new form shows up, you install React Hook Form, add Zod or Yup, and in ten minutes you have something that "works." The problem doesn't surface that day. It surfaces three months later, when the same VIN you validate in the create car form also has to be validated in edit , in import from Excel , and it turns out the rule —"17 characters, the last 5 numeric"— is written three times, each one slightly different, and none of them lives in a place you can point to and say "here is what a valid VIN is." A typical form with a library looks roughly like this: const schema = z . object ({ vin : z . string (). length ( 17 , " The VIN must be 17 characters " ), miles : z . number (). min ( 0 , " Miles cannot be negative " ), // ...and 8 more fields }); const { register , handleSubmit , watch , formState : { errors }, } = useForm ({ resolver : zodResolver ( schema ), }); It works. But if you stop to look at it, you're paying three costs that almost never get named: 1. Clean code dissolves. The business rule ends up scattered across the schema , the resolver , the register calls, the Controller s, and the JSX. The knowledge — what makes a car valid — has no home. It's wired into the UI. And what's wired into the UI doesn't get reused: it gets copied. 2. Performance and coupling are paid silently. These libraries live on subscriptions: watch , re-renders on every keystroke, internal state to keep in sync. For a contact form, who cares. For a screen with 15 fields, sub-forms, and cross-field validation, your component is tied to the library's lifecycle —not yours— and you start fighting it instead of using it. 3. Developer convenience is a trap. It's wonderfully convenient at first . But that same rule: how do you test it without mounting a component? How do you move it to the backend? How do you translate it into two languages without polluting the schema? Everything the library gave you for free, it charges you for the day you need to step outside its mo

The Quest Begins (The “Why”) Picture this: I’m knee‑deep in a legacy codebase that feels like the Death Star’s trash compactor—every time I try to add a feature, the walls close in and I’m squashed by tight coupling. I’d just spent three hours tracking down a bug that only showed up when the payment gateway was mocked in a test. The culprit? A new PaymentGateway() buried deep inside an OrderService class. It was like trying to defeat Darth Vader with a butter knife—no matter how hard I swung, the Dark Force (aka hidden dependencies) kept pulling me back. I realized I was instantiating collaborators inside the very classes that should be oblivious to their implementation details . The result? Tests that needed a real database, a real Stripe account, and a sacrificial goat to run. Any change to a third‑party API meant hunting down every new scattered across the project. Onboarding a new teammate felt like handing them a map written in ancient Sumerian. Honestly, I was ready to quit coding and become a professional napper. Then, during a late‑night coffee‑fueled refactor session, I stumbled upon a tiny line of documentation that whispered: “Depend on abstractions, not concretions.” It sounded like Yoda giving me a pep talk. The Revelation (The Insight) The magic spell I uncovered is Dependency Injection (DI) —specifically, constructor injection . Instead of a class creating its own collaborators, we hand them in from the outside. Think of it as giving a Jedi their lightsaber rather than making them forge one in the middle of a battle. Why does this feel like discovering the Force? Testability explodes – you can swap in fakes, mocks, or stubs without touching production code. Flexibility skyrockets – swapping a payment provider becomes a one‑line config change, not a scavenger hunt. Clarity reigns – the constructor becomes an honest inventory of what a class needs to do its job. The moment I applied it, the codebase felt lighter, like Luke finally trusting the Force ins

By Sergio Colque Ponce — Software Engineering, Universidad Privada de Tacna. Full source code: github.com/srg-cp/design-principles-go When people say "this code is well designed" , they rarely mean it has clever tricks. They usually mean it is easy to change . New requirements arrive every week, and good design is what lets you absorb them without rewriting half the project. In this article I take a small, very common requirement — "send a reminder to the user" — and I show how four classic design principles turn a fragile module into one that is open to change and easy to test. Everything is written in Go , and you can run it yourself from the repository linked above. The requirement We are building the backend of a bank appointment system. When an appointment is created, the user should get a reminder. Today it goes by email . Next month, product wants SMS too. After that, WhatsApp . The pattern is obvious: the list of channels will keep growing. A first (bad) attempt The fastest thing to write is one function that does everything: func SendReminder ( channel , recipient , body string ) error { if channel == "email" { // ... open SMTP, format the email, send it } else if channel == "sms" { // ... call the SMS provider } else if channel == "whatsapp" { // ... call the WhatsApp API } return nil } It works on Monday. But look at what it costs us: Every new channel means editing this function and risking the ones that already work. The function knows about SMTP, SMS providers and HTTP clients all at once: it has many reasons to change . To test the email path you need a real (or faked) SMTP server, because the logic is glued to the transport. This is the design we want to avoid. Let's fix it one principle at a time. 1. Single Responsibility Principle (SRP) A piece of code should have one reason to change . Instead of one function that knows every channel, we give each channel its own type that only knows how to deliver through that channel. Here is the email one: // E

The One TDD Habit That Saved My Sanity (and My Codebase) Quick context (why you're writing this) Here's the thing: I used to think I was doing TDD right. I’d write a test, watch it fail, then write just enough code to make it green. Rinse and repeat. Sounds textbook, right? But a few months ago I spent an entire afternoon chasing a bug that only showed up after I refactored a service class. The tests were all passing, yet the app was throwing NullReferenceExceptions in production. I was shocked. How could everything be green and still be broken? Turns out I was testing the inside of my code instead of what it actually did for the outside world. That realization hit me like a truck, and it completely changed how I approach TDD. The Insight Test behavior, not implementation. If your test is coupled to private fields, internal data structures, or the exact way a method accomplishes its goal, you’re not testing what matters—you’re testing how you happen to do it today. When you later refactor to improve performance, swap out a dependency, or even just rename a variable, those tests start failing for no good reason. You end up spending more time fixing tests than delivering value, and you lose confidence in the suite because it feels fragile. The payoff? A test suite that gives you confidence when you change code, not anxiety. You can refactor fearlessly because the tests only care about the contract: given these inputs, the system should produce these outputs or side‑effects . How (with code) Let’s look at a tiny but realistic example: a PasswordValidator service that checks whether a user‑chosen password meets our policy. ❌ The mistake: testing implementation details // PasswordValidator.cs public class PasswordValidator { private readonly IRegexProvider _regex ; // injected for testability public PasswordValidator ( IRegexProvider regex ) { _regex = regex ; } public bool IsValid ( string password ) { // implementation we might want to change later return _regex . IsMa

As the web has evolved, so have the strategies for rendering content in browsers. Two of the most widely used approaches today are Server-Side Rendering (SSR) and Client-Side Rendering (CSR). Each has its strengths and trade-offs, and understanding when to use one over the other is key to building fast, scalable, and user-friendly applications. This article explores the key differences, benefits, and common use cases of SSR and CSR, with practical examples. What is Client-Side Rendering (CSR)? Client-Side Rendering means that the browser downloads a minimal HTML shell and renders the content using JavaScript. Most of the work, fetching data, templating, and updating the DOM, happens in the user's browser after the page loads. Benefits Rich interactivity: Ideal for dynamic single-page applications (SPAs). Fast navigation after initial load: Once loaded, switching between views is instantaneous. Great for app-like experiences: Think dashboards, SaaS tools, or email clients. Drawbacks Slower initial page load: The user sees a blank screen until JavaScript loads and executes. SEO challenges: Search engines may struggle to index dynamic content, unless SSR or prerendering is used. Poor performance on slow devices: All rendering logic happens in the browser. What is Server-Side Rendering (SSR)? Server-Side Rendering generates the full HTML on the server for each request. When a user visits a page, the server fetches the data, compiles the HTML, and sends it to the browser, which then hydrates the app into an interactive component. Benefits of SSR: Fast time-to-first-byte (TTFB): HTML is ready and shows up immediately. Better SEO: Search engines receive fully rendered pages. Good for public-facing content: Blogs, marketing sites, e-commerce pages. Drawbacks Increased server load: Every page request triggers rendering logic. Longer time to interactivity: HTML loads quickly, but hydration takes extra time. Requires server infrastructure: Cannot be purely deployed as static f