No special messages at the moment. Just have a good day and stay hydrated!
Close

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.

Name

"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://github.com/Droogans/unmaintainable-code.

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 🙂.



Sponsor

I hope this article was useful to you! Consider checking out my sponsors. I can continue to write quality articles for free because of them.

Discussion

Thoughts? Share the article if you think it'll be useful to someone + join the discussion about this post on Twitter!


Stay in touch!



About the author

Khalil Stemmler

Khalil Stemmler is a Developer / Designer and co-founder of Univjobs. He frequently publishes articles about Domain-Driven 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

Domain Knowledge & Interpretation of the Single Responsibility Principle | SOLID Node.js + TypeScript
Jun 13th, 2019 / 8 min read
The Single Responsibility Principle specifies that a class or function should only have one reason to change. Admittedly, that's n...
SOLID Principles: The Software Developer's Framework to Robust & Maintainable Code [with Examples]
May 18th, 2019 / 15 min read
The SOLID principles are a set of software design principles that teach us how we can structure our functions and classes to be as...
TypeScript vs. JavaScript [Pros / cons]
May 11th, 2019 / 4 min read
TypeScript is arguably one of the best things to come to the JavaScript world helping developers comfortably create complex enterp...
UML Cheatsheet | Resource
Apr 26th, 2019 / 1 min read
Here's a handy-dandy UML cheatsheet.

Want to be notified when new content comes out?

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

I won't spam ya. 🖖 Unsubscribe anytime.

Get updates