DEV Community: Leonardo Gomes

Organization Isn't Just About Code — It's About Team Process

Leonardo Gomes — Fri, 03 Jul 2026 01:22:58 +0000

In Part 1 of this article (link to part 1 here), I talked about organizing the code itself: architecture, Clean Code, and SOLID. But well-written code isn't enough if the team around it doesn't have a clear process for versioning, documentation, and workflow. That's what I want to talk about now.

I Had Been Doing It for a While — I Just Didn't Know the Name

I remember a coworker asking me to "create a feature branch off of develop." I did it almost without thinking, since it was exactly what I'd already been doing for years. But that's when it hit me: "wait... does this have a name?"

That's how I found out that "automatic" workflow I'd been using — stable main branch, feature branches, isolated hotfixes — already had a formal name: Git Flow.

And that wasn't the only time. Earlier in my career, it was common to follow instructions ("do it this way," "follow this pattern") without understanding why, or even knowing there was theory behind it. Practice arrives before the name, and only later — out of curiosity, or in a conversation with another dev — do you discover the formal label for what you were already doing. It's not a lack of competence, it's just the natural order of day-to-day learning.

I think that says something about how we pick up good practices — and sometimes bad ones too 😅

We often internalize a behavior out of necessity, and that doesn't automatically make it right or wrong — only later do we chase down where it actually came from. It's normal to take time connecting "the name to the thing." And it's worth being careful here: it's easy to assume a process is correct or a best practice just because someone told you to do it that way, when really you might just be holding onto a habit. Staying curious, researching, and studying alongside hands-on experience is what builds real clarity over time — and lets you explain the process clearly to whoever joins the team next. Sharing technical knowledge about the project you're working on is also part of your responsibility, which is exactly why it matters so much.

Documentation: The "Clean Code" Nobody Reads But Everyone Misses

Documentation tends to get treated as a second-class task — until the day someone new joins the team and has no idea how to set up the environment or why a certain architectural decision was made. A well-written README, a few strategic comments (not excessive ones), and recorded architecture decisions save, without exaggeration, days of work over the life of a project.

Scrum, Kanban, and the Right Fit for Each Context

On the process side, I work with a mix of Scrum and Kanban depending on the nature of the project. For deliveries with clear deadlines and scope, Scrum's sprint rhythm helps create predictability. For ongoing maintenance or smaller squads, Kanban's visual flow tends to fit better, without the overhead of ceremonies that don't always make sense for small teams.

Agile methodology isn't about following a rulebook — it's about creating visibility into what's being done and reducing communication friction between whoever's coding and whoever depends on what's being coded. Many think it's overkill or unnecessary process, but it's precisely in its absence that its value becomes obvious.

In the End, It's About the Next Developer

Bringing both parts of this topic together — clean architecture, SOLID principles, well-defined versioning, documentation, and an agile process that actually makes sense — it all converges into one question I try to ask myself before every Pull Request: if someone else opens this code tomorrow, without me around, will they understand what I did and why?

This topic is broad enough that I'm sure there are other techniques and methodologies out there I haven't come across yet, and I'd love to learn them. So tell me — what did you think? Any tips to add? What are some things you were already doing without knowing there was a technical name for it? 😅

Let's discuss it below 👇

If this content resonated with you, drop a like and share it with someone who deals with this kind of team challenge too. And if you want to follow more of what I'm building, find me on LinkedIn, GitHub, or my portfolio.

Why Organizing Your Code Matters More Than You Think

Leonardo Gomes — Fri, 03 Jul 2026 01:17:38 +0000

There's a specific kind of pain only developers who've opened a team repo truly understand: you look for a function, it's not where it should be, nobody followed the same pattern, naming is inconsistent (PascalCase mixed with camelCase), business rules live in the wrong place. You start feeling lost, want to refactor everything, and what should've been a 10-minute change turns into a full afternoon of "treasure hunting" and patch-fixing.

With over 6 years working as a fullstack developer, I've been through multiple teams and projects with fairly complex business rules — enough to learn, in practice, that code that works is not the same as code that's organized. And on a team, that difference decides whether a project scales or turns into a maintenance nightmare.

While writing about this topic, the piece grew large enough that I split it into two parts. In this first one, I cover how the code itself should be structured and written: architecture, Clean Code, and SOLID. In the second part, I cover how the team organizes around that code: Git Flow, documentation, and agile methodology.

Architecture as a Contract Between the Team

Before getting into more elaborate architectures, the first pattern that really opened my eyes on this topic was MVC (Model-View-Controller). That's where I understood, in practice, the value of separating "what holds the data," "what displays the data," and "what decides what to do with the data." It sounds basic today, but MVC is what taught me that code organization isn't about aesthetics — it's what determines whether a team can work in parallel without stepping on each other's work.

Over time, one of the concepts that most shaped my growth was Clean Architecture, by Robert C. Martin ("Uncle Bob"). The core idea is easy to state and hard to practice: your system's business rules shouldn't depend on technical details like the database, framework, or UI. It should be the other way around — those details should depend on the business rules. In a way, it's a natural extension of what MVC already pointed to: separating responsibilities so each part of the system can change without breaking the others.

In practice, this means structuring the project in layers (entities, use cases, interfaces) in a way that lets anyone on the team, upon opening the repo, understand what the system does before understanding how it does it. In projects with external integrations and frequently changing business rules — something I've experienced firsthand — this separation is what allows new rules to be added without rewriting half the system every time.

It's not about rigidly following every layer from the book as dogma, nor about abandoning MVC. It's about having clear boundaries and knowing where one responsibility ends and another begins — whether with three layers or ten.

Clean Code and SOLID: The Foundation That Holds the Architecture Up

If architecture is the skeleton, Clean Code (also by Uncle Bob) is what ensures each part of that skeleton stays readable and maintainable. The SOLID principles — single responsibility, open/closed, Liskov substitution, interface segregation, and dependency inversion — aren't academic; they solve real maintenance problems that show up constantly once more than one person touches the same code. Each principle has its own application, and it's not always possible to apply all of them for various reasons, especially on a project that's already underway or wasn't designed with SOLID in mind from the start. What matters is understanding and practicing what you can :)

Working in a collaborative environment means keeping continuous improvement in mind. It's nearly impossible to fix everything at once, but it helps to keep the "Boy Scout Rule" in mind: leave the campsite cleaner than you found it. Every commit is a chance to improve or document some odd piece of code you ran into, for future improvement (code smell: it works, but it doesn't smell right). Don't be the dev who "pretends not to see it."

So How Does the Team Organize Around This?

So far, I've covered the code itself: how to structure it (architecture) and how to write it (Clean Code and SOLID). But code organization doesn't live in isolation — it depends directly on how the team versions, documents, and runs its workflow.

That's exactly what I cover in Part 2 of this article: Git Flow, documentation, and the agile methodology I use day to day. If you want to understand how these technical pillars hold up in practice at the team level, it's worth the follow-up read 👉 link to part 2 here