Reveal intent, hide implementation

#javascript #beginners #webdev #code

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));

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);

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.

🦄 Let's stay connected on Instagram

Top comments (5)

Mike Talbot ⭐ • May 19 '20

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

Sebastian • Jun 7 '20 • 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!