What I joined

The product worked, and people were shipping from it. But every change cost more than it should have, because the codebase had grown without shared conventions:

  • File structure and UI were inconsistent from one area to the next.
  • The same components had been rebuilt several times in slightly different ways.
  • Form validation was only partly implemented.
  • Some files had grown very large and mixed data access, state, and presentation.
  • Success and error feedback looked and behaved differently depending on the screen.
  • The README no longer described how the project actually worked.

One branch, one reviewable change

Fixing these things a little at a time inside feature work tends to produce a third convention rather than one shared one. I did the work on a separate branch instead, so it could be reviewed and validated as a whole before it touched the shared codebase.

What changed, and why it mattered
AreaBeforeAfter
StructureFiles organised differently in each areaA modular structure grouped by feature, with shared code in one predictable place
ComponentsRepeated, slightly different versions of the same UIReusable components, integrated across the project
FormsValidation partly implementedComplete validation on every form, with errors presented the same way
Large filesData access, state, and presentation mixed togetherResponsibilities separated so each file has one job
FeedbackSuccess and error messages handled screen by screenOne shared notification system
Look and behaviourInconsistent UI and interactionsConsistent, brand-aligned UI and interaction behaviour
DocumentationREADME out of dateREADME updated to match the actual project
Illustrative feature-based structuretext
src/
  app/            routes and app-level providers
  components/     shared, reusable UI
  features/
    <feature>/
      api/          requests for this feature
      hooks/        data and state hooks
      model/        types and validation
      components/   UI used only by this feature
      pages/        screens that compose the pieces above
  shared/         utilities used across features

Validation and adoption

I validated the changes with unit tests and manual QA. The team then adopted the standards for ongoing work, so new features follow the same structure, components, validation, and feedback patterns.

Adoption mattered more than the branch itself. A convention only helps if the next person to touch the code follows it, and that is far more likely when they can see it working in the codebase than when it’s a document they’re asked to read.

What I learned

  • Large files are a signal to look at responsibilities, not a problem in themselves.
  • Shared feedback and validation are product decisions as much as code ones. People notice when the same mistake gets two different messages.
  • An accurate README is part of the standard. New contributors learn the conventions from it first.
Back to top