My TypeScript Software Design & Architecture book just prelaunched! Check out

Name, Construct & Structure | Organizing Readable Code - Part 1

This article is from "Name, Construct & Structure". Get it while it's free.
Jun 15th, 2019 / 6 min read / Share / Edit on GitHub
Naming files & folders well, using well-understood technical constructs and strategically organizing files well are three ways to improve our ability to change code quickly.

This article is part of a 32-page ebook titled "Name, Construct & Structure". It, as well as the SOLID Book are available free for a limited time before it becomes available only on Gumroad. Grab it [here].

Have you ever come back to an old codebase feeling completely daunted by having to re-learn everything?

Have you ever entered into a sizable codebase and felt like none of the files or folders gave you any hints as to what the contents were?

Have you felt like it was way too hard to understand w​hat things are,​ ​what they do,​ and w​here they’re located?

Similarly to how UX designers spend time understanding how users use their products and come up with ways to reduce friction, there's a similar art to structuring codebases.

After spending some time really thinking about structuring projects, learning Domain-Driven Design, Design Patterns, and reading Uncle Bob's "Clean Architecture", I think I've found a good pattern for structuring large codebases and naming files & folders that works really well for myself and my team.

It comes down to three things.

Name, construct & structure.

In this article, we'll talk about Name.



“There are only two hard things in Computer Science: cache invalidation and naming things”. -- Phil Karlton

Choosing names for c​lasses,​ ​files, ​and f​olders​ can be incredibly hard sometimes. However, it’s kind of important to put some effort into it.

It’s important because the goal of naming things is to inform the reader as quickly as possible about what something is​​.

How do we do that? How do we name things so that it quickly informs the reader what it is​?

Tips for picking good names

Here are a few of the approaches that I use for most cases. Having these in my back pocket enables me to usually never spend more than a couple of seconds thinking about a name.

Approach #1: Name files by Domain + Construct

When naming f​iles, ​I’ll often choose names based on the s​ubdomain it belongs to ​+ the c​onstruct type.

You might be wondering, “what’s a domain”?

"Domain definition"

Secondly, we should understand what c​onstructs a​re.

"Construct definition"

Since we understand what s​ubdomains a​nd c​onstructs​ are now, we could use them to assemble names for our files by appending the c​onstruct​ type to the s​ubdomain (or element from the subdomain - see below).

"Choosing names"

Let’s see what some of that might look like in principle.

"Choosing names"

It’s a good start, but there’s a problem. W​e’re not organizing our subdomains properly​.

Things from the J​ob ​​subdomain are mixed up with the U​sers ​​subdomain. That’s definitely giving me clutter-y feels.

It’s time to think about naming folders.

Approach #2: Name folders by Subdomain, and (optionally) Subdomain + Construct

Naming folders by the name of the subdomain ​is a great way to segment code so that you can focus on one particular part of your project at a time.

Here’s a start.

"subdomain organized code"

That’s better, but you might still feel a little bit discombobulated looking at this many files at one time. I like to take the next step of also creating sub-folders and naming them by the c​onstruct type.​

"organize by construct  type"

I like this a lot. We talk about it more in P​art 3: Structure, ​but this is called “Packaging by Component”.

There’s a construct for everything

If we can’t decide on a good name for a file, it might be because w​e don’t know​ what type of construct the class in our file actually is.

So beware of naming things “etc-manager” and “etc-implementor”, because when we start to do that, files become harder to understand what they’re s​ingularly responsible for ​at first glance.

If you’re finding that you’re often not sure what type of construct to use, my suggestion is the following:

Learn Design Patterns

Design patterns tend to be pretty narrowly scoped solutions to common problems in software.

Because of that, they communicate well with other developers that are familiar with them.

For example, when I started getting into D​omain-Driven Design​​ and realized that I needed to convert a J​ob​ model to different formats (to a Domain entity, to an ORM representation, to a DTO, etc), I went looking for a pattern. I discovered that the pattern was the D​ata Mapper pattern​.

From then on, anytime I realize I need to do this particular behavior, I name it an “​[EntityName from Domain]Mapper​”.

So dig around a little bit! That’s the best way to learn design patterns. By actually having problems that need to get solved, to looking for the correct tool for the job, to implementing it, you’ll find that you retain that information much deeper rather simply going through the entire catalog of design patterns.

That being said, the best resources for to sift through are these books:

  • Martin Fowler’s book called Patterns of Enterprise Application Architecture
  • GoF: Design Patterns Book
  • PoSA: Pattern Oriented Software Architecture Book

Also, if you want to learn how to write cleaner code overall, check out “Clean Code” by Robert C. Martin (Uncle Bob). It’s a great read.

Bad names

If you want to see an entire list of ways to d​ o evil and keep your job forever, ​check out this repo: h​ttps://

Look out for too many helper/utility/service classes

It’s easy to call just about everything a “helper”, “utility” or “service”.

Understanding if something should be a h​elper​ comes from having knowledge about the domain.

I’ve talked about this topic quite a bit h​ere ​and h​ere (anemic domain models).​

In the next sections, we'll talk about how understanding what construct to use in addition to which domain it belongs to enables us to organize clear architectural boundaries.

Want the book?

This article is part of a 32-page ebook titled "Name, Construct & Structure". It, as well as the SOLID Book are available free for a limited time before it becomes available only on Gumroad.

Want it? Get the free 32-page PDF 🙂.


Liked this? Sing it loud and proud 👨‍🎤.


Be the first to leave a comment


Stay in touch!

About the author

Khalil Stemmler,
Developer Advocate @ Apollo GraphQL ⚡

Khalil is a software developer, writer, and musician. He frequently publishes articles about Domain-Driven Design, software design and Advanced TypeScript & Node.js best practices for large-scale applications.

View more in Software Design

You may also enjoy...

A few more related articles

Comparison of Domain-Driven Design and Clean Architecture Concepts
Nov 5th, 2019 / 8 min read
Eric Evans' "Domain-Driven Design" and Uncle Bob's "Clean Architecture" are books that have introduced tactical approaches towards...
How to Learn Software Design and Architecture | The Full-stack Software Design & Architecture Map
Sep 28th, 2019 / 17 min read
Software Design and Architecture is pretty much it's own field of study within the realm of computing, like DevOps or UX Design. H...
The 6 Most Common Types of Logic in Large Applications [with Examples]
Sep 16th, 2019 / 12 min read
In this article, you'll learn about the Clean Architecture, why we should separate the concerns of large applications into layers,...
Why I Don't Use a DI Container | Node.js w/ TypeScript
Sep 16th, 2019 / 11 min read
Instead of a DI Container, I just package features by component and use logical naming conventions.

Want to be notified when new content comes out?

Join 3000+ other developers learning about Domain-Driven Design and Enterprise Node.js.

I won't spam ya. 🖖 Unsubscribe anytime.

Get updates