标签：#cleancode

The Quest Begins (The "Why") I still remember the first time I opened a legacy codebase and felt like I’d stepped into a dark dungeon without a torch. The file was a single 800‑line function called processData . Inside, variables bore names like tmp , x , flag , and comments that tried to explain every line: // TODO: refactor this mess function processData ( input ) { let r = []; // result array for ( let i = 0 ; i < input . length ; i ++ ) { // loop over items if ( input [ i ] > 10 ) { // if value greater than threshold let v = input [ i ] * 2 ; // double it if ( v % 2 === 0 ) { // if even r . push ( v ); // add to result } } } return r ; } I spent three hours tracing why a certain edge case produced an empty array, only to discover the comment “if value greater than threshold” was outdated—the threshold had changed to 12 in a later commit, but the comment never got updated. The code lied, the comments misled, and I felt like a hero who’d just swung at a shadow. That frustration sparked a question: What if we could write code so clear that comments became unnecessary? Not because we’re lazy, but because the code itself tells the story. The Revelation (The Insight) The treasure I uncovered wasn’t a new framework or a slick library—it was a mindset shift: make the code self‑documenting through intention‑revealing names and small, focused functions . When a variable, function, or class name reads like a sentence, the reader can infer what’s happening without a side note. Think of it like reading a well‑written novel. You don’t need footnotes to understand that “She opened the door and stepped into the rain” means she’s going outside. The same principle applies to code: if you name a function filterValuesAboveThreshold , the intent is obvious. Why does this matter? Because comments decay. They become outdated, they get ignored, and they add noise. Self‑explanatory code, on the other hand, stays accurate as long as the name stays accurate. It also forces you to think ab

Ele começou com um if . Hoje tem 80 linhas. Sabe como é: precisava barrar quem não tem assinatura ativa. Um middleware, três linhas, resolvido. Depois entrou o período de teste. Depois o plano legado que tem regra diferente. Depois "aproveita que já buscou a assinatura e desconta um crédito". Depois o e-mail de aviso quando faltam 3 dias pro vencimento. Hoje esse arquivo tem 80 linhas, faz quatro queries, altera dado no banco e dispara e-mail. Ele não é mais um middleware. É um Service que mora na pasta errada e roda em todo request. E o pior: essa regra não existe pro resto do seu sistema. O middleware que virou gerente class VerificarAssinatura { public function handle ( Request $request , Closure $next ): Response { $assinatura = $request -> user () -> assinatura ; if ( ! $assinatura || $assinatura -> venceu ()) { return redirect () -> route ( 'planos' ); } // "aproveita que já tá aqui" 🙃 if ( $assinatura -> creditos < 1 ) { return redirect () -> route ( 'planos' ) -> withErrors ( 'Sem créditos' ); } $assinatura -> decrement ( 'creditos' ); $assinatura -> update ([ 'ultimo_acesso' => now ()]); if ( $assinatura -> vence_em -> diffInDays ( now ()) <= 3 ) { Mail :: to ( $request -> user ()) -> send ( new AssinaturaVencendo ( $assinatura )); } return $next ( $request ); } } Funciona. Passa nos testes de feature. E tem quatro problemas escondidos que só aparecem meses depois. Problema 1: middleware só existe no HTTP Esse é o grande. Middleware é uma camada de request HTTP . Ela não roda em outro lugar nenhum. Então: O comando php artisan relatorio:gerar não desconta crédito. O job na fila não desconta crédito. Sua rota de API que você esqueceu de agrupar não desconta crédito. O tinker passa por cima de tudo. Você não criou uma regra de negócio. Criou uma regra da porta da frente . Qualquer outra entrada no sistema ignora ela. E, sério, isso não é hipótese: um dia alguém vai criar um endpoint novo, esquecer o middleware, e a assinatura vira um detalhe decorativo. Probl

The Quest Begins (The "Why") I still remember the first time I opened a pull request that looked like a novel written by someone who’d had too much coffee. The file was 800 lines long, a single function tried to validate input, fetch data from three different APIs, transform the result, update the UI, and log everything to a console that no one ever looked at. I spent three hours stepping through it with a debugger, only to realize the bug was a typo in a variable name buried three levels deep in a nested if‑statement. When I finally fixed it, I felt like I’d just defeated a dragon… only to discover the dragon had a dozen smaller dragons hiding in its caves. That experience left me wondering: Why does code feel so hard to read, even when it works? The answer wasn’t a fancy framework or a new language feature—it was a simple habit I’d overlooked: making every function do one thing, and do it well . Once I started treating that rule like a sacred oath, the dragons started to shrink, and my code began to feel like a clean, well‑lit hallway instead of a dark, tangled forest. The Revelation (The Insight) The principle is straightforward, yet its impact is massive: each function should have a single responsibility . If you can describe what a function does with a single verb phrase— validateUserInput , fetchUserProfile , renderDashboard —you’re on the right track. If you need an “and” or a “but” in that description, you’ve probably got more than one job packed in. Why does this matter? Readability : A reader can grasp the intent in seconds, not minutes. Testability : Small, focused functions are trivial to unit test. You can mock dependencies and assert outcomes without setting up a whole saga. Debugging : When something goes wrong, the stack trace points you directly to the guilty function, not to a 20‑line monolith where you have to hunt for the offending line. Reusability : A function that does one thing well can be dropped into other parts of the codebase (or even oth

Ask any AI coding assistant directly whether using array index as a React key is a good idea, and it will tell you no. It will explain why. Reordering, insertion, and deletion of list items can cause React to misidentify which DOM node corresponds to which data, leading to state bugs and unnecessary re-renders. This is not obscure knowledge. It is one of the most commonly repeated pieces of React advice that exists, and every model has clearly seen it thousands of times during training. And yet, if you look through a codebase where the AI generated a meaningful portion of the list rendering, you will very likely find at least one instance of exactly this pattern. A map over an array, using the index as the key prop, sitting quietly in a component that otherwise looks perfectly reasonable. This is a strange thing to observe once you notice it. The AI is not confused about the rule. Ask it directly and it recites the correct answer immediately and confidently. But somewhere between knowing the rule in the abstract and applying it consistently during generation, something gets lost. Why knowing a rule and applying it are different things There is a meaningful difference between an AI model having encountered information during training and that information reliably surfacing during every relevant generation task. When you ask directly whether index as key is a good idea, you are prompting the model to retrieve and state a fact it has strong, well reinforced associations with. This is a different cognitive task than generating a list rendering component from scratch while simultaneously handling several other decisions about structure, naming, data shape, and styling. During active generation, the model is not running through a checklist of best practices for every line it writes. It is producing output token by token based on patterns, and in the moment of writing a map function, the path of least resistance is often exactly the pattern that gets flagged as wrong when

Introduction to Clean Architecture Clean architecture, a software design philosophy championed by the renowned Robert C. Martin (Uncle Bob), has revolutionized the way developers approach system design. By prioritizing the separation of concerns and promoting independence From frameworks, user interfaces, and databases, clean architecture empowers developers to build robust, maintainable, and scalable systems. This design approach is not just a theoretical concept, but a practical solution for real-world problems. In this guide, we'll explore the principles of clean architecture and provide a step-by-step roadmap for implementing it in your own projects, so you can get started with clean architecture and Unlock its full potential. Independent of Frameworks: Your business logic shouldn't depend on external libraries Testable: Business rules can be tested without UI, database, or external services Independent of UI: You can swap web UI for console UI without changing business logic Independent of Database: You can swap SQL Server for MongoDB without changing business rules Independent of External Services: Business rules don't know about external services Core Principles Clean Architecture organizes code into concentric circles, with dependencies pointing inward: 1. Entities (Inner Circle) These are the business objects of your application. They contain enterprise-wide business rules and are the most stable part of your system. public class User { public string Id { get ; set ; } public string Email { get ; set ; } public string Name { get ; set ; } public bool IsValid () { return ! string . IsNullOrEmpty ( Email ) && Email . Contains ( "@" ); } } 2. Use Cases (Application Layer) This layer contains application-specific business rules. It orchestrates the flow of data to and From entities. public class CreateUserUseCase { private readonly IUserRepository _repository ; public async Task < User > Execute ( CreateUserRequest request ) { var user = new User { Email = requ

int(os.environ.get("PORT", "8080")) fails constantly in ways that waste your time: ValueError: invalid literal for int() with base 10: 'abc' . No variable name. No hint about what a valid value looks like. You grep the codebase for PORT to even find where the read happened. specenv is a zero-runtime-dependency Python library for typed environment variable loading — casting, validation, schema grouping, prefix namespacing. All of that is useful, but none of it is the actual design decision worth writing about. The decision that shaped everything else was: every error must name the variable and say how to fix it, unconditionally, with no opt-out. Decision 1: The error message is generated at the failure site, not templated afterward It would be easy to build one generic EnvCastError(var_name, raw_value, target_type) and format a message from those three fields in __str__ . specenv doesn't do that — each cast failure builds its own message inline, at the point where the specific failure is known: if cast_type is int : try : return int ( raw ) except ValueError : raise EnvCastError ( f ' Cannot cast { name } = { raw !r} to int. \n ' f ' → Set { name } to a valid integer (e.g. { name } =8080) ' ) from None if cast_type is bool : ... raise EnvCastError ( f ' Cannot cast { name } = { raw !r} to bool. \n ' f ' → Set { name } to one of: 1/0, true/false, yes/no, on/off ' ) The generic version would produce "Cannot cast PORT='abc' to int" and stop there. The inline version gets to add (e.g. PORT=8080) for ints, 1/0, true/false, yes/no, on/off for bools, a namespaced hint for prefixed variables — because at the point of failure, you know exactly what a correct value looks like for that type, and a generic formatter three calls up the stack doesn't. The cost is a few lines of duplication across _caster.py 's type branches. That's a fair trade for every single error message being genuinely actionable instead of generically accurate. Decision 2: Missing-and-required collapses to t

The most dangerous overengineering does not look careless. It looks thoughtful. It has clean interfaces, reusable components, configurable behavior, extension points, and an architecture diagram that makes the system appear ready for anything. Then the next feature arrives. A change that should take one afternoon touches seven layers, breaks three abstractions, and forces the team to understand a framework built for requirements that never appeared. That is what makes overengineering difficult to recognize. It rarely presents itself as unnecessary complexity. It presents itself as responsible engineering. It Usually Begins With a Reasonable Fear Developers do not overengineer because they want to make systems harder. They usually remember an earlier project that became painful. Maybe duplicated business logic spread across several screens. Maybe a component could not support a second use case. Maybe an integration became impossible to replace. Maybe a narrow implementation eventually required an expensive rewrite. The next time a similar problem appears, the team tries to protect itself. What if this feature grows? What if another team needs it? What if product asks for configuration? What if we add more providers? What if the rules change? These are reasonable questions. The problem begins when imagined requirements receive the same architectural weight as real ones. A single approval flow becomes a workflow engine. Two similar components become a universal rendering framework. One pricing exception becomes a configurable rules platform. The team tries to avoid future pain and creates immediate friction instead. The first use case now has to support requirements that do not exist. Developers must understand extension points nobody uses, configuration nobody needs, and interfaces protecting boundaries that have not appeared. Thinking about the future is not the mistake. Building the future before there is evidence is. Reuse Is Expensive Before the Pattern Is Stable

When building scalable systems, we often need a collection of classes to expose a fixed, read-only configuration value. Whether it is a unique API_ENDPOINT, a DATABASE_TABLE name, or a specific PERMISSIONS_MASK, handling constants across a series of classes looks simple on day one but can quickly turn into an architectural nightmare. Setting the Foundation: How to Make It In modern object-oriented programming, the standard way to declare a constant on a class is by leveraging the static readonly modifiers. This ensures the attribute belongs to the class itself, rather than an instance, and cannot be mutated at runtime. TypeScript class BillingService { static readonly SERVICE_TYPE = "BILLING"; } class InventoryService { static readonly SERVICE_TYPE = "INVENTORY"; } This works perfectly when you know exactly which class you are dealing with at compile time. You simply call BillingService.SERVICE_TYPE and move on. The Architectural Breakdown: What Will Be the Problems The clean code facade breaks the moment you attempt to handle these classes dynamically. In production environments, you rarely hardcode class names; instead, you process them as an array or a series of registry keys. Loss of Type Safety: If you pass a series of these classes into a processing function, standard type systems will treat them as generic constructor functions, wiping out access to the static property unless you resort to unsafe type casting. Polymorphism Failure: Subclasses do not inherently enforce or override static properties cleanly through standard interfaces. You cannot enforce a static readonly property on an interface, meaning a developer could easily forget to define the constant on a new service class, causing silent runtime failures. Instance vs. Class Metadata Confusion: If your architecture receives an instance of the class rather than the class definition itself, accessing the static attribute requires jumping through hoops like instance.constructor.SERVICE_TYPE, which breaks

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