DEV Community

Coding Unicorn 🦄
Coding Unicorn 🦄

Posted on

Reveal intent, hide implementation

When writing code, it's important to distinguish between INTENT (what is happening) and IMPLEMENTATION (how things work).

❌ In the example below, intent is mixed with implementation:

users
  .filter(user -> user.registrationDate.isBefore(dayjs().minus('years', 1)) && user.hasPurchases())
  .filter(user -> authenticationService.isAuthenticated(user));
Enter fullscreen mode Exit fullscreen mode

In order to understand WHAT this code is doing, your brain has to discern INTENT from IMPLEMENTATION. You need to spend 5-10 seconds on deliberate thinking. It consumes your limited and precious brainfuel. And that's only a single method.

✅ Now, let's improve the code. Let's leave the intent visible, but implementation hidden:

users
  .filter(isLoyal)
  .filter(isAuthenticated);
Enter fullscreen mode Exit fullscreen mode

It's immediately clear WHAT the code is doing. The code is not polluted with implementation details; details are hidden. Leaving only essential information and removing the noise is called abstraction. A well-abstracted code is easy to scan. A poorly abstracted code requires a lot of deliberate thinking and attention.

🧠 Remember: good code reveals intent, but hides implementation details until they are needed. Make the essence visible; hide the rest.

Alt Text

🦄 Let's stay connected on Instagram

Discussion (5)

Collapse
miketalbot profile image
Mike Talbot

Just so right. Everything we make is effectively a series of Russian dolls, seeing the fraught intricate detail of an inner implementation adds massively to cognitive load.

It's a style thing though - I think a lot of people just want to start coding as they think - if you can get in the habit of WRITING the way you suggest, it becomes second nature. You write the filter and just put a name in there that does what you want, then you write the function.

I'm "ok" at this. Looking at my code right now I can see I've done this a lot for complex functions but I guess I'm inconsistent on what level of complexity...

const localFields = useFields(target.document)
        .filter((f) => f.name)
        .compact(true)

Yay, useFields isn't listed out in full detail - but hmm - what is that intention about f.name...

const localFields = useFields(target.document)
        .filter(isStoredInRecord)
        .compact(true)

Much better... I'm off for some refactoring

Collapse
lifelongthinker profile image
Sebastian • Edited

Perfectly explained. 👏👏

Code that tells a story is maintainable, declarative, intention-revealing code (what?, not how?) comes first and is used to hide the implementation (how?), hide the information that may be irrelevant to the one reading your code, or label it in case it IS relevant: Here you have to look.

It is one of the principle guidelines that seem easy to follow but are actually very hard to out into practice every day, for you can easily slip into bad habits. We all have been there, and we owe it to the ones coming after us to pass this on.

Thanks for your contribution!

Collapse
vonheikemen profile image
Heiker

this reminds me of a phrase I heard once, "friends don't let friends play compiler."

Collapse
codingunicorn profile image
Coding Unicorn 🦄 Author

This one is really good :))

Collapse
adam_cyclones profile image
Adam Crockett

I know this is off topic, but what's the story with that dress, it's ace, I want a hoodie like this!