Every project starts out clean. Then haste arrives, along with “I’ll clean it up later,” and six months later nobody can find where the business rule lives—not even the person who wrote it.
The folder tells a story—or it should
Open the root of a project and you should be able to figure out what it deals with just by looking at its structure. If the top-level folders are utils, helpers, services, and components, you have learned nothing about the domain—you have learned about the framework, which is the least important part.
Prefer a structure that reflects the business: checkout, billing, catalog, users. The technical layer is a detail inside each one. A new developer should be able to point to “the discount rule is here” without opening ten files to figure it out.
Separation of responsibilities without the dogma
Separation of responsibilities has become an excuse to create ten layers and a pile of interfaces nobody understands. That is not the point. It is simple: each piece of code should have a reason to exist and, preferably, a single reason to change.
The practical test is the commit. If changing a pricing rule forces you to edit the UI component, the controller, a utility, and an enum, those things are not separated—they are scattered, which is the opposite. Put together what changes together and isolate what changes for different reasons.
A good name is one you do not have to explain
A name reveals intent. processData() says nothing—processes what, for what purpose? calculateShipping() tells the whole story before you even open the function body.
Do not save characters at the expense of clarity. usr, tmp, d, and flag2 cost you every time someone reads the code again—and code is read far more often than it is written. If you need a comment to explain what a variable stores, its name has already failed. Spend the extra seconds writing pendingOrders instead of arr.
A large file is hidden debt
An 800-line file almost never does just one thing. It started out doing one thing, kept growing, and became a dumping ground for “I don’t know where to put this, so put it here.”
Break things up by responsibility, not by some arbitrary line count. The right measure is cognitive: a file should fit in your head. You open it, understand what it does, and leave without scrolling through three screens or keeping five concepts in mind at the same time. When you hesitate over the file name because it does “several things,” that is the sign that it should be two files.
Colocation beats layers in most cases
A rule that solves 80% of cases: keep together what changes together. Put the test next to the code it tests, the style next to the component, and the hook near the code that consumes it.
Separating everything by technical type—a giant /tests folder, a giant /styles folder, and a giant /hooks folder—looks organized in a screenshot, but in practice it forces you to open four distant folders to understand a single feature. And when you delete the feature, leftover debris remains scattered across all of them. Colocation also makes the most honest task easier: deleting things.
A README is not decoration
A README that explains how to run and test the project, and where important decisions live, saves hours for every new team member—and for you three months from now, when you have forgotten.
But be careful: documentation that lies is worse than missing documentation, because you trust it and make the wrong decision. The rule is to treat documentation like code: if you change the build command, update the README in the same commit. Documentation that lives far from the code always goes stale.
Code organization is not aesthetic fussiness or the obsessive satisfaction of someone who likes perfectly aligned folders. It is about the team finding things quickly and changing the system without fear. You do not need to refactor the whole world today—just make the next file you touch a little more obvious than it was.
