Forem: Aurelio

Lunch break talks #2: Things I wish I knew when I was younger

Aurelio — Wed, 18 Nov 2020 22:16:17 +0000

I like to watch talks during my lunch breaks, so I share some of the best ones I bump into, along with my notes.

There are at least 3 reasons why a talk from Simon Sinek is pretty much always worth your time:

He picks simple yet clever and entertaining topics
He is a great motivator
He's one of the best public speakers around.

See for yourself.

"See the bagel"

Cafeteria tables, aligned next to each other and a long line of runners hoping to get a free bagel. So I said to my friend "Let's get a bagel".
He looked at me and said "No man, the line is too long".
And I looked at him and said: "It's a free bagel!"

2 ways you can see the world. You can see the thing you want, or you can see the thing standing in the way
Focus on your goals, not on what's standing in the way
If you focus on the end result, the obstacle is an opportunity for innovation

Perspective matters

Interpret nerves as excitement. Same symptoms (heart beat, sweat etc), totally different mindset
Being nervous (negative) vs being excited (positive)

Give yourself to your team members selflessly

The highest performing teams on the planet are not the strongest, not the strongest, not the fastest. They are the ones that give to each other selflessly
"You are here because someone took care of you and you have the responsibility to take care of others. This is the core of leadership".

Listen first, speak last

Be a great listener by allowing others to talk first
Ensure they feel listened
Great leaders don't start the conversation, they end it
Practice to be the last to speak when you're part of a team

Don't panic

Don't panic, so people around you stay calm
We confuse moments of happiness with fulfilment
Fulfilment is entirely different

"We all deserve a styrofoam cup"

Hear the story
Rewards and accolades are given not to you, but to the position you hold

Bagel image is by Kreated Media
Cup image is by Marco Chilese

The #1 ingredient of a successful team

Aurelio — Sun, 15 Nov 2020 22:43:07 +0000

Have you ever wondered what makes a team a great one?
I never did, until I had to create one.

The recipe of a great team

My first instinct would have been to hire just enough people and strive for a balance of various traits distributed across the members:

good communication
highly skilled
drive to learn and improve
positive attitude

These are certainly the traits that define a remarkable co-worker, but they are not telling me anything about the team dynamics that I should be striving for.
So the question still stands, what makes a team a great one?

Let's stand on the shoulders of giants and look for the answer

As it often happens, it turns out I'm far from the first one to ask this question.
In 2015 Google published a research aimed at answering this exact same question.
The result was in fact that:

Who is on a team matters less than how the team members interact, structure their work, and view their contributions

In their research Google highlighted five dynamics that set successful teams apart from average ones, and the first of them is psychological safety.

What is Psychological Safety and why does it matter?

Psychological safety was first theorised by Harvard Business School professor Amy Edmondson.
In her book "The Fearless Organization: Creating Psychological Safety in the Workplace for Learning, Innovation, and Growth" she outlines the definition of this term and why it is the fundamental trait of successful teams.

I have defined psychological safety as the belief that the work environment is safe for interpersonal risk taking

-- Amy Edmonson, "The Fearless Organization: Creating Psychological Safety in the Workplace for Learning, Innovation, and Growth

We can define Psychological Safety as the climate where anyone in the team feels free to speak up.

The traits of a psychologically safe environment

How does one know if they are in a psychologically safe environment? Let's see what are the consequences we would see in such a team:

It's safe to ask for help
Admitting mistakes is the norm
Anyone can discuss existing problems
New ideas are shared
Learnings are shared
Criticising a project is possible
Raising issues with management is accepted, even when these issues come from the managers themselves
Giving feedback to any other colleague is a regular occurrence
Feedback is acted upon

What Psychological Safety is not

Edmonson clarifies in her book and in many of her interviews what Psychological Safety is not. I find this distinction very important to drive the idea in the right direction, as it might be easily misunderstood.
Safety is not about:

Being nice
Being soft
"Everything is great" attitude
"Everything will work out" attitude
Low ambition

And finally, safety is not a personality trait. It's a team trait.

How does Psychological Safety exist within a team?

Psychological safety is a deliberate investment. It doesn't happen by itself or by chance. It's not the result of the chemistry of the team members.

It's the result of a proactive, continuous effort of the management and the team members to instil this value on a daily basis in the fibre of a team. Managers need to create an environment where making mistakes is accepted and talking about them is encouraged so much that it's the norm.

A side effect of mistakes being surfaced frequently is that either new processes are created or existing ones are perfected. This constant rework of the status quo is what sets great teams apart.

Who should invest in Psychological Safety?

In one word: everyone. And by everyone I mean:

Companies as they will create a place where skilled and ambitious people want to be in and hence attract talent
Managers as they will build high performance teams that deliver and are capable of overachieving
Employees as they will improve their career and discover new professional paths that would otherwise remain unknown to them
People looking for a new job as they will want to understand their future team dynamics so they can find a place that match their ambitions, allow them to onboard faster and contribute quickly and effectively

Looking back: an interesting game

Once I learnt about Psychological Safety, I started playing a game in my head.
Of all my past teams, can I rate how psychologically safe those places were?
Unsurprisingly, the teams that scored higher were also the ones where I learnt the most and felt that I could make an impact.

What about you? How did your past team or your current one score?

Cover image by Clarissa Watson

Should my small team really, really, really do code reviews?

Aurelio — Fri, 06 Nov 2020 22:41:03 +0000

While nearly everyone on paper agrees that code reviews are "a good thing" and everyone should do them, the reality often tells a different story.

Big teams and companies all pretty much have a code review process in place. On the other hand, small startups often skip this step, especially at the early stages of their life.

Note: If you're short of time feel free to skip at the last section and get a quick list of to-dos.
(And by the way, the answer to the question in the title is yes)

When you shouldn't do code reviews

Or rather, how people justify their team skipping reviews.

Code reviews slow us down
We're all senior developers, we trust each other
We will start code reviews as soon as it makes sense
We're only 2 developers, why should we?
It's a quick change, it's ok

If you recognise yourself in one or more of the above statements, I hope this post will convince you to reconsider.

Let's talk about code quality

Code reviews are one of the best way to favour accountability and "good quality code". If done right, they can be better than any linting tool, code style guide or automated process.

Having someone proof read what we type helps us keeping our standards higher. Even a seasoned developer can slip sloppy code in the codebase when tired, be it consciously or by mistake.
But code quality comes at a cost, and the money used to pay for it is one of the most valuable currencies for a startup: time.

It seems commonly accepted that doing things right is slower than doing them worse.
Martin Fowler talks about this in his article "Is High Quality Software Worth the Cost?". He mentions something interesting for us:

Developers find poor quality code significantly slows them down within a few weeks [emphasis mine]. So there's not much runway where the trade-off between internal quality and cost applies.

this chart is taken from Fowler's article

If we agree on Mr Fowler's take we can see that "good code" pays off very quickly, even at very early stages.
Higher quality means higher velocity, and this is true earlier than many seem to realise.

While the first lines of a new codebase are often seen as something temporary ("it's only a prototype after all"), the reality is that those lines will influence the speed of development very early on. In a few weeks this advantage will very likely be noticeable.

What to review

When it comes to code reviews, sometimes the question arises about what exactly to review. From what we've seen so far it's perhaps clear that my suggestion is that every new piece of functionality or any meaningful change should go through code review from day 1.
But what about very small changes? What about a quick readme update?

I keep it simple, do code review absolutely everything. Every single PR should be peer reviewed. And yes, this "unfortunately" means no pushing to straight to master, no "this is a quick one" PRs that go in unreviewed.

Sounds harsh? Maybe. But it's very hard to draw a line of what exactly is a meaningful change and what is a trivial one. Is a 200 lines indentation tweak worth more or less than a 1 line change in the models of your application? Even a readme update can contain misleading information or be based off wrong assumptions. And if we allow very small changes to go through by skipping review, what's the threshold that divides what's to be reviewed from what's not? How do you explain this to the next dev joining?

If it's a quick change, it will also be very quick to review.

But, but... this slows me down!

I hear you. Yes. You're pushing a one-liner and I'm telling you that you need to wait 2 hours, or even a day for someone else to review it.
I agree, this is unacceptable. And that's why having prompt reviews should be a top concern of your team processes.

We're in a small startup and speed is everything. Well, it turns out, speed is everything at massive scales, too.

At Google, we optimize for the speed at which a team of developers can produce a product together, as opposed to optimizing for the speed at which an individual developer can write code

-- From Google Engineering Practices Documentation

Here are the guidelines from Google:

If you are not in the middle of a focused task, you should do a code review shortly after it comes in.
One business day is the maximum time it should take to respond to a code review request (i.e. first thing the next morning).
Following these guidelines means that a typical PR should get multiple rounds of review (if needed) within a single day.

Your startup is fast, your reviewers should be too.
If you're looking for a nifty tool to automatically track how fast your team is I suggest Velocity.

How thorough should your reviews be?

Reviews don't mean quickly scrolling through dozens lines of code and pressing "approve", perhaps adding a thumbs up to add a human touch to it.
It's very important to actually read and understand the code. If we are always very permissive we will get sloppy and just let anything go in. If you - on the contrary - make a habit of reading critically and making an effort to understand what's going on, then it will get normal to ask questions and clarifications on many PRs.

This will make commenting a part of the daily routine of the company. When it'll be time to be more critical regarding an approach taken in code it will be less likely to cause a stir or be a source of litigation.

Reading the code also means that knowledge spreads faster within the team. Code reviews are not just about code quality, they are also about knowing what's happening around the codebase while you're not looking.

Read the code, and understand it. If you don't, ask questions.

Who should be assigned to reviews?

In super small teams this is a non issue, you don't have much of a choice.
When the team grows, the question of who should review might arise.
In my view:

Many assignees are better than fewer
Aim for at least 2 reviewers, if the team's size allows. Look at how you can make this a policy with Github's protected branches
Also have junior devs do review.
I repeat, have junior devs do reviews!

If you want to make assigning people faster, you can use Github's codeowners that will automatically assign for you. Open a PR and you're done.

One extra tip: comment your own PRs

Adding comments to a PR should not be limited to other people's PRs. You can add comments to your own ones as well.
I'm not the only one doing this and I find it really helpful when someone does it.

You can anticipate questions, explain why you've taken a certain approach, tell the reader that you already have a follow-up PR in mind.
This, again, will make reviews faster.

In short

I hope by now I convinced you that code reviews are an investment that have short and long time benefits that even an early stage startup should consider.
Here's a quick list of action items for the busy ones and a recap for everyone who read so far.

Do code reviews from day 1
Review every single change, no matter how trivial
Require "Pull request reviews before merging". See how on Github
Use codeowners so you don't have to waste time picking reviewers.
Strive for fast code review turn arounds. Maximum waiting time should be one day, but preferably it should be quantified in minutes. Read how Google does it.
You can track your team's speed and impact of code review by using tools like Velocity
Be thorough when reviewing, understand what you're reading. Avoid giving thumbs up to absolutely everything, without reading.

Cover image by Thom Milkovic on Unsplash

How I remember everything I learn

Aurelio — Sun, 01 Nov 2020 00:03:17 +0000

Have you ever been asked this question:

If you could have just one superpower, which one would you choose?

It's one of those questions that can either leave you frozen without any actual clue what to say or you might catch yourself with so many ideas that you're simply overwhelmed by the abundance of options.

Unrelated: the most clever answer to this question I've read is this one by the way.

(not a bad idea, right?)

There's no right or wrong of course, but if you asked me, my answer would be something like:

I would be able to remember everything I learn

I don't know about you, but knowledge retention is easily one the big challenges of my life. I read blogs every day, I watch countless videos, I start (and sometimes finish) a few technical books per year and remembering everything I learnt is outright unrealistic.
There's just so much one can retain of what they read or hear.

What I tried

If you're like me, you've tried them all:

blogging about it
highlighting the most important sentences of the books you read
taking physical notes
taking notes online (eg Evernote)
writing summaries of the books and videos you read
flash cards
semi-organised (or semi-random), heavy bookmarking with tools like Pocket
you name it

All these methods have their merits. All of them ultimately fall short for me.
Some worked better than others but I couldn't for the life of me stick to one.

An impossible balance

I felt I was somehow looking for an impossible balance. I wanted a solution that:

was structured...
...but still loose enough so it didn't kill my creativity and the free flow of thoughts that happens when learning something new
searchable
low friction, as in, easy to type in, giving me a pleasant, natural experience
non-existent learning curve (no "new revolutionary tools"). Sorry, I'm busy leaning something else
easily retrievable, available anywhere
recoverable if a disaster happens (think about forgetting your notebook on a train, or having it chewed by your dog)
trackable, I wanted to be able to see my progress through the months, and possibly get some stats, if not for vanity

Turning point

I was resigned to never find a solution for it.
Until one day, I randomly bumped into this

I’ve been extending and improving my personal wiki for 1 year now and it has been one of the best things I’ve done. I found writing blog posts was too high friction and very often didn’t finish things because there is so much you can talk about in any given article. But a wiki is just a living document containing your notes and thoughts on things. I also use it as my public bookmark manager as I collect interesting to me links under each topic.

For my wiki, I render everything to the web first with GitBook. And I have a macro I run that automatically commits any changes I’ve made with Sublime Text on the mac and Ulysses on the phone so everything is super easy to edit and publish.

Does anyone else keep their own wiki here? Or you think a blog is enough for you?

-- Nikita Volobev on Lobsters

And there it was. The sign that the "impossible balance" was actually possible.

From that moment, around 2 years ago, I also created my own personal wiki and it's been my go-to tool for remembering everything I learn.

It's nothing more than a repo on Github, divided in folders with a bunch of READMEs in each of them.
Folders are the main categories, such as databases, Kubernetes, JavaScript, security, regex etc. Each README inside them subdivide the folder into specific topics. Security would have READMEs for JWT, Frontend, Cryptography etc.

Evolution

I initially started with only programming topics but found myself using the wiki to store notes about literally anything I learn in any domain such as music, writing, managing, speaking and writing German.

The structure is not super strict, but still provide some order and thanks to Github searching is absolutely a breeze.

Since everything is committed, I wrote a small Go program to calculate some stats by accessing the git history and generate an HTML page. A Github action runs the script and publishes it to a URL. The page looks - let's say - minimal (it has literally 3 lines of CSS), but it gives me an overview of what I have been learning in the past 90 days. Apparently I've been very much into career development and management as of late.

Giving it a try

I strongly recommend giving this method a try if you're also struggling with knowledge retention.
The investment to start is so low, you literally only need to create a repo and that's it, and you can even fork mine and simply delete most of the folders if you like.

Nikita and I are not the only ones using this method. You can find plenty others for inspiration by going through this long list of wikis.

Cover image by Osman Rana

$ considered harmful

Aurelio — Sat, 04 Jul 2020 05:23:38 +0000

One of the most satisfying feelings in life is waking up at 5am, going to the kitchen to drink a glass of water while casually scrolling through Twitter on your phone and finding someone (on the Twitter feed, not in the kitchen) that is right on the internet*:

// Detect dark theme var iframe = document.getElementById('tweet-1277199020268703744-208'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1277199020268703744&theme=dark" }

* Where right means: someone else is saying something you always thought of, but never quite found time/space/willpower/occasion to express to a wider audience or even to yourself.

Disclaimer

Let's begin with a disclaimer: this is a clear case of first world problem that really has no great meaning in the grand scheme of things, and the arguments against it are still valid. I just found it amusing to see I wasn't really the only one being mildly frustrated by it.

I also think that the discussion that ensued is interesting and worth reading.

Problem

When setting up a project you might need some setup and most of the times this involves running a handful of shell command. An example:

$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python
$ pyenv install 3.7.6
$ pyenv local 3.7.6

Ok, now try copy pasting those 3 lines in one go... Chances are you will see as output something like this:

zsh: command not found: $

Isn't this irritating?

What does `$` even mean

There are a few reasons why $ is prepended to every line of a shell command example:

it indicates that indeed, what you are looking at is a command that is meant to be run in a shell
It indicates that you need to run this command as a user, and not as root

Why you should not remove `$`

Some valid arguments in favour of keeping the $:

You should never trust commands on the internet and blindly copy paste them

// Detect dark theme var iframe = document.getElementById('tweet-1277464720728035331-36'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1277464720728035331&theme=dark" }

You should communicate when to run a command a root (using #) and when not ($)

// Detect dark theme var iframe = document.getElementById('tweet-1277201037321998338-336'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1277201037321998338&theme=dark" }

The case for removing `$`

makes it harder to copy, especially multiline commands
not everyone might be aware of # meaning "run as root"

In the thread another user makes an great point

// Detect dark theme var iframe = document.getElementById('tweet-1277990481884901376-850'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1277990481884901376&theme=dark" }

How to remove `$`

If you have read so far and sort of agree that we might be better off not including the $ in shell samples, here's a few ways to make it happen.

The easy way

Just don't type it! This applies to Github and pretty much all places where you have no control over how code samples are rendered. A post on Dev.to is one example.

So this

$ pyenv install 3.7.6

becomes

pyenv install 3.7.6

if a command is meant to be run as root prepend it with sudo

sudo apt-get install ubuntu-desktop

The stylish way

If you have control over the rendering and you still like you readers to see the $, consider using CSS to remove it from the text that ends up in the clipboard when copying. In the thread, Twitter user @beccadottex shares a Codepen of how this can be done.

@theconfigurator shares another one here

// Detect dark theme var iframe = document.getElementById('tweet-1277279975654281216-111'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1277279975654281216&theme=dark" }

Should you really stop using $?

As any other opinion based topic, there seems to be far from an agreement on the best practice around this, as the long thread on Twitter shows.

As for myself, I always found it redundant and pointless but funnily enough I found myself using it out of habit. From now on, I will purposefully keep the $ out of my docs.

/rant

comic at the beginning is a ripoff of Xkcd's Duty Calls
cover image is by Ryan Quintal.

D3: a JS library for the next 10 years?

Aurelio — Wed, 29 Apr 2020 07:18:56 +0000

D3 has been the go-to library for in browser data visualisation for many years by now.
While JavaScript libraries are notorious for being extremely transient and easily replaced by newer, shinier alternatives, for some reason this does not seem to apply to D3.

Some history

The first published version I can trace by searching between npm and Github releases is 1.24.1 which is dated 2nd July 2011, although the first version ever seems to be from February that year, i.e. over 9 years ago at the time of writing. This means we're closing in to the first decade of d3.
In the JavaScript world this is probably the human equivalent of a century ago.

To give a bit of perspective, Backbone was created around that time, and so was AngularJS version 1.x (remember $scope.apply()?)
The JavaScript ecosystem has completely changed during this time, in terms of libraries, best practices and even language features.

Nevertheless, D3 is still here. And it's more popular than ever.

The Present

This chart is taken from Npmtrends and shows the last 5 years of npm downloads of D3 compared to Chart.js and Highcharts.
D3 emerges as a clear winner, and this is not even considering the fact that many users are not downloading the full library (the entire d3 package), but only some of its modules, such as d3-array, or d3-scale.

6 reasons for the long-lasting success of D3

I can think of a few reasons why D3 is yet to be replaced by an alternative. In my view, they actually make it unlikely to be replaced any time soon.

Stable

The biggest API change in D3 happened during the major upgrade from 3 to 4 as far as I know. From there on, the api has been pretty much the same.

Thoroughly tested

D3 has an excellent test coverage and has been used in production for years now by thousands of developers. In fact D3 is almost...

Bug free

Ok, this is an exaggeration. There's no such thing as a program with no bugs, and D3 is no exception.
Still, the number of issues is very limited, especially compared to competing charting libraries that have hundreds of open/unresolved issues.

This is a screenshot of the D3's main repo on Github, with a whopping 3 open issues.

Actively maintained

You can look at the latest version publish, or the latest commit on Github, or the planned features in the roadmaps. This makes it clear that the idea is to go on and keep D3 up to date and in line with modern JS.

Modular build

One of the biggest criticisms towards D3 has historically been its staggering size. For years, including D3 on a page meant adding a great amount of kBs to your page. Since version 4 the library has been split into several standalone, dedicated modules. This means that you can include in your bundle only those part of the library that you actually leverage in your code.

The improvement in terms of size is remarkable. Let's visualise what this means. Here's the composition of d3 version 3.5

In this case adding D3 for a simple bar chart meant including totally unrelated stuff like functions to draw map projects (d3-geo), parsers and formatters for dates in a variety of locale-specific implementations, force layout helpers... In short, a lot of potentially useless code was added to the bundle.

Let's compare it to the 5.x version

This means that nowadays we can install only what's needed for the specific visualisation and leave the rest of D3 out of the bundle.

All these are valid points but wouldn't suffice to explain why D3 is still a relevant, desirable choice for anyone making visualisation. The missing one is...

Philosophy

This is in my opinion the single most important reason of the list, and it's where all of the points above really come together in shaping a great library that will - in my opinion - stand the test of time.

D3 is not a Data Visualization Library

-- Elijah Meeks

D3 is not really a charting library, it doesn't even have the concept of a chart. Rather, its goal is to provide the most common primitives to perform any type of mapping, mathematical operation or analysis on data. Like Lodash is the de-facto standard when it comes to data manipulation, D3 is the obvious choice when dealing with data analysis.

In short, no matter how JS will evolve, you'll still need to do the same computations to draw charts and to map raw data to x and y coordinates, or to easily map a range of values to a range of colours.

The basics of data visualisation and how to perform mathematical calculations are not going to change any time soon.
Since D3 operates at that low level, and in such a modular way, the reasons to find or even write an alternative library are very limited and not compelling enough.

For me, this fundamental approach is what sets D3 apart from any other solution out there, and the key reason for the long-lasting success of the library.

A lot of people seem not to be big fans of how D3 handles updating DOM (look at d3-selection) and it certainly can be quite intimidating. I am not going to discuss here about the D3 DOM api, or give any personal opinion, but again, the modularity of D3 means that you can always swap its selection methods with view libraries like React or Vue, and use D3 for calculation.

Some library authors have decided to do just that. Two examples of this approach are Victory and VX

Conclusion

In conclusion, I think D3 is unlikely to be superseded by an alternative and, by the looks of it, it will remain the de-facto standard for the foreseeable future.
This does not mean it's perfect and that it comes with no disadvantages (one for all, the steep learning curve) but it's certainly still very much relevant, if not more than it ever was.

It also does not mean that every one that needs to draw a chart on a page need to learn it. But if you're serious about data visualisation and want to have full freedom when it comes to plotting data in a browser then D3 is arguably going to be your best bet.

Cover Image: Rene Bohmer

Lunch break talks #1: Simplicity is complicated

Aurelio — Wed, 27 Nov 2019 13:59:41 +0000

I sometimes like to watch a talk during my lunch breaks, so I decided to share some of the best ones I bump into, along with my notes.
I try to keep the topics fairly language agnostic (after all it's a lunch break).

In this case the talk is from Rob Pike, one of the creators of Go. It still resonates with me, even if I am writing JavaScript pretty much all day. Simplicity is a goal at any level you're writing (not just when writing a language!) and it is a hard thing to achieve.

I really like that Rob Pike makes everyone think about how hard it is to architect the grammar of a language, and how hard it is to take decisions and make tradeoffs when designing a new one. Funny how just a few days ago I was wondering why Go was not providing a filter or map method for arrays or slices, and he actually answers it during this talk.

Such an inspiring video that I think every programmer should see, even if not interested in Go!

My key key take aways:

New features

a lot of languages are adding new features (coff... coff.. JavaScript...)
a lot of this new features are the same ones across languages
these languages are starting to look very similar one another
if programmers use very similar languages, they will start to all think the same way
in reality, what you ideally want, is a language that is very good at solving domain specific problems

Complexity

more features equals more complexity
Go has added a very small set of features
how to pick the right feature to add? By picking only the right ones!

Readability

more features means more time spent thinking about how to write something
ideally you want a language to allow for one way - or at least not many ways - of writing a thing
a smaller feature set makes it more maintainable in the long run

Simplicity

a lot of thinking has to be put to achieve simplicity
GC is one example of it in Go. A very difficult feature to implement that is 100% hidden from the end user, or even from the spec
the interface to the user might be simple, even the implementation in the language might be simple, but the design of a feature is very likely to be a long, difficult process
a lot of complexity might lie behind very simple code. He makes a fantastic walkthrough of a simple server written in Go and what's happening behind the scenes here

Bottom line is, simplicity is hard to get, but - if you get it right - makes doing complicated things easy to achieve for your users.

Working with environments in Postman

Aurelio — Wed, 30 Oct 2019 13:27:44 +0000

Postman is one my favourite tools at work to test APIs.
Even at a simple level Postman easily becomes invaluable. At the same time, devoting a little effort in learning some of its best features can quickly boost our productivity and development speed.

One of my favourite aspects of working with Postman is its environments feature.

Life without Postman environments

Before explaining what an environment is in the context of Postman, I'd like to list a couple of the most common scenarios I face when working with an API.
This will make it easier to understand why and when environments are useful.

One of the most common cases is having to hit an endpoint that requires some sort of authentication.
Say, for example, that we are hitting http://localhost:3000/users to retrieve a list of users that are registered on our platform.
The server expects the user that performs the call to be authenticated to make this call. To accomplish this a client may expect to pass a token as part of the request, say as an entry in the headers in the form of a JWT token.

The easiest way to do that is to first hit our authentication endpoint (for instance http://localhost/auth), passing a username and password, inspect the response on the Postman UI and manually copy this token. We would then be able to paste this token as a header for future requests, such as the above example to request the list of users.

While this works, it becomes tedious quickly as we will need to paste the token in every new tab we create on Postman. Moreover, every time our token expires, we will have to repeat the process of hitting the auth endpoint, and copying our new token.

Let's see how we can avoid this manual setup thanks to Postman.

Learn how to work with environments

As you will see, environments are a very powerful feature to stay organised in Postman and to make our workflow much faster and portable.
If you want to follow along and try all the steps below you can clone this repo, follow the instructions in the readme to install and test every command against this test api.

Open Postman and click on the cog on the top right section of the UI.

Choose a unique name for your project, and fill in 2 variables, URL and Authorization.

In the picture I added an initial value of localhost:3000 for URL, since I am running my server locally at first, while I left the auth field blank.
With this setup we can start hitting the auth endpoint and make use of our first variable in Postman.

Save the values and select the newly created environment from the "Environments" dropdown on the top right of the UI.

Create a new request by typing the endpoint we want to hit into the main input field.
We want to hit localhost:3000/auth, but instead of hardcoding the host we will use the environment variable we just created, by replacing localhost:3000 with {{URL}}.
This means that localhost:3000/auth will become {{URL}}/auth. Postman will confirm URL is defined while we type via and autocomplete popup.

Once the url is typed we send the request and sure enough, we have our token back. This is of course the least secure of the APIs since we're not even passing an email password combination, but that's ok for a test server!

We now want to extract this token from the response and assign it to our other env variable, Authorization.
To do so, select the "Tests" tab and type this:

// read response
var res = pm.response.json();
// set Authorization to the jwt token
pm.environment.set("Authorization", res.jwt);

This easy 2 liner gets the response and sets it to our env variable. We can confirm it works by running the request again and then clicking on the top right eye icon (Quick look environment variables).
We will see the value being populated.

This is great, as now we'll be able to make request without manually pasting the token.
To do so we just need to open a new tab in Postman, paste the full URL of one of our authenticated endpoints, such as {{URL}}/users and, in the request headers make use of our newly set variable. Click on "Authorization" and select "Bearer token" under the Type dropdown. Paste our variable in the one field available.

Once done we are ready to send a request to an endpoint that requires authentication, such as /users and see the results.

Getting more out of Postman environments

This simple workflow is just the tip of the iceberg of the many advantages of Postman variables and environments.
The configuration we just created can be saved and shared to other devices or to other colleagues that are working on the same project.
More examples and suggestions can be found on the excellent docs of Postman.

Why I stopped spreading props on React Components

Aurelio — Mon, 19 Aug 2019 23:34:41 +0000

Spreading props on a React Component is a very common pattern that I picked up very easily and loved from day 1.
With time though I learnt to understand the implications of using the spread operator in different contexts and came to the conclusion that most of the time spreading props in React is best avoided. Let's see why.

I stopped spreading props... but not quite

Use spread props sparingly

First of all I want to start with a clarification. The title of this post is misleading on purpose (read: clickbaity). Props spreading has its share of good use cases and is an expressive and concise pattern that can be used effectively.

A good scenario to demonstrate how props spreading can really shine is HOCs. Let's look at this example.

const withDouble = Comp => props => (
// We could wrap any type of Component here so we just pass all props down as they are
  <Comp {...props} value={props.value * 2} />
);

const SomeInput = ({ onChange, value, disabled }) => (
  <input value={value} disabled={disabled} onChange={e => onChange(e.target.value)}/>
);

const Doubled = withDouble(SomeInput);

const MyCal = () => {
  const [val, setVal] = React.useState(0);

  return (
    <>
    <SomeInput value={val} onChange={setVal} />
    <Doubled value={val} disabled />
    </>
  );
}

You can try the above code here.

MyCal is a bare-bones, extremely limited calculator that only doubles the input we type on a field.
In this case we use withDouble as a generic wrapper that can wrap and enhance any component.
As such it must remain unaware of the props that it will forward down the tree.

Being able to spread props like so <Comp {...props} /> is really powerful because we are free to enhance any component we might have. In the example above we can see that passing 'disabled' later on will actually work exactly for that reason.

<Doubled value={val} disabled /> // this prop will be forwarded to `SomeInput` that will render a read only field

Beautiful is better than ugly.

Let's look at how SomeInput is implemented.

const SomeInput = ({ onChange, value, disabled }) => (
<input value={value} disabled={disabled} onChange={e => onChange(e.target.value)}/>
);

Now that we're in love with our new skill of spreading props, we might be tempted to do this:

const SomeInput = ({ onChange, ...props }) => (
<input {...props} onChange={e => onChange(e.target.value)}/>
);

This looks much more appealing at first glance - at least to me - and I won't deny a part of me is pleased with how succinct this looks like.

If we try that the component will work just the same. The problem we just introduced may not be apparent for now, but we have lost control over which prop our underlying input will receive. Try this and you will see that randomProp will be happily forwarded to <input /> itself.

<SomeInput onChange={alert} randomProp={2} />

Had we kept our original implementation the stray property would just have been ignored.

const SomeInput = ({ onChange, value, disabled }) => (
<input value={value} disabled={disabled} onChange={e => onChange(e.target.value)}/>
);

<SomeInput
  onChange={alert} // known props, it will be passed down
  randomProp={2} // unknown one, ignored
/>

While this might seem simplistic, problems like these become more and more common as the size and complexity of the codebase grow. Applying layers and layers of Components that just pass down props without any sort of check will make it very hard to follow where data flows, and which attributes are applied where.

In the face of ambiguity, refuse the temptation to guess.

The latest example makes the case for using a type checker, to help flag non-existing props.
Actually introducing type definitions on an existing codebase with spreads all over the place is not the most pleasing experience either.
If you're into TypeScript or Flow try writing a type def this:

const MyComp = ({
  type,
  value,
  ...rest
}: Props) => (
  const className = type === 'round' ? 'Btn--round' : 'Btn';

  return (
    <Actionable className={className} {..rest}>{value}</Actionable>
  )
)

type Props = {
  type?: 'round',
  value: React.Node
  // and??
}

Guessing value and type is quite straightforward. What about the ...rest though? How should the shape look like?
We either become sloppy and allow any, which makes me question why we're even trying to type this thing, or we have to open the 'Actionable' implementation, check how props are handled there and hope that there's not another spread there (which is highly possible) otherwise we'll have open yet another file.

Once done that I would also check all instances of 'MyComp' to make sure random or outdated props are not passed by mistake. If this sounds tedious it's because it is.

Let's compare it to this other implementation.

const MyComp = ({
  type,
  value,
  colour,
  size,
  onClick,
  onHover
}: Props) => (
const className = type === 'round' ? 'Btn--round' : 'Btn';

return (
  <Actionable
    onHover={onHover}
    onClick={onClick}
    className={className}
    colour={colour}
    size={size}>
      {value}
  </Actionable>
  )
)

While we can't be 100% sure about every single type in this list of props we can do a lot without looking any further.

type Props = {
  type?: 'round',
  value: React.Node,
  colour: string,
  size: string | number,
  onClick: () => void,
  onHover: () => void
};

While this is not perfect, it's miles better than what we have above. I would even say this next lousy effort is better than the first! At least we're listing out all the acceptable props!

type Props = {
  type?: any,
  value: any,
  colour: any,
  size: any,
  onClick: any,
  onHover: any
};

This concept might seem specific to typings, but I think it represents very well the difference in terms of cognitive effort required when reading code written in one way or the other.

By listing our props we stay away from pitfalls and ensure clarity for the readers of our code.

Explicit is better than implicit.

In conclusion, while spreading props is a powerful pattern we must be aware of its drawbacks and conscious that this technique has its place and merits, but is certainly not a silver bullet.

Having props listed out clearly helps us communicate intent and capabilities of our functions. Spreading them can be used to serve a purpose, but should never come at the cost of readability or safety.

References

With time I saw that the pitfalls of spreading props are actually documented in more than one official piece of documentation.

Spread attributes can be useful but they also make it easy to pass unnecessary props to components that don’t care about them or to pass invalid HTML attributes to the DOM. We recommend using this syntax sparingly.
React docs

The first quote at the beginning of the article is from Airbnb's JavaScript Style Guide.

Also, you might be interested to know that:

There's more than one reference in this article that comes from the Zen of Python.
Cover image is by Lachlan Dempsey

Originally published on my blog.

Compound scales in D3.js

Aurelio — Fri, 09 Aug 2019 15:14:14 +0000

Scales are an extremely flexible feature of D3.js.
Even though in many cases our need is just to have a function that maps one value in the domain to one value in the range, sometimes it can be handy to have a mapping from one to many values.

Suppose for example that we need to map one input to a set of values such as color and radius to build a simple scatterplot where the dots have radius and color depending on the input value from the dataset.

In these case being able to have a compound scale is what we need, and thankfully D3 provides this feature out of the box. Just pass two (or more) objects to the range function and d3 will do the rest.

Here’s a simple example:

const myScale = scaleLinear()
  .domain([0, 100])
  .range([
    {color: '#4c0080', radius:'15px'},
    {color: '#43a1ad', radius:'150px'}
  ]);

This code will return a function that will convert our values (in this case from 0 to 100) to an object with all the values appropriately interpolated.

For example:

myScale(41); // => {color: 'rgb(72, 66, 146)', radius: '70.35px'}

A simple yet super-handy feature, especially considering that we don’t need to specify the interpolator because the library will figure it out for us. On top of that we are not tied to single level objects, but deep objects will work just the same.

Credits

Image is by Markus Spiske.

Originally published on my blog.

Array methods in D3.js

Aurelio — Sun, 04 Aug 2019 22:09:24 +0000

Arrays are the natural data structure for looping over data in JavaScript. While the native methods such as map, reduce, filter etc will provide a good base for pretty much any operation on arrays, many libraries and frameworks enrich the native set of functions with domain specific utilities.

D3.js, the de facto standard library for data visualisation in Js, is no exception. D3 actually provides d3-array, an entire module of utility functions that covers many of the most common operations when dealing with data and visualisation.

Let’s see how we can leverage some of them, starting from the most commonly used ones.

Installing and using the module the right way

First of all lets point out that it is strongly suggested installing and importing the d3-array module only, rather than the whole d3 module.

This means that rather than this:

// npm i -s d3
import d3 from 'd3';

d3.min([1,2,3]);

You will want to do this:

// npm i -s d3-array
import { min } from 'd3-array';

d3.min([1,2,3]);

This avoids downloading and bundling the whole d3 library. D3 has in fact moved to a fully modularised build since v3. This means we can install only the pieces we need, without incurring in a hefty penalty in terms of bundle size.

If you're curious to see which modules d3 exports, you can see them nicely listed in the index.js.

To illustrate some of d3's array manipulation features let’s start with two dummy datasets, a sparse, unsorted array of random numbers, data:

const data = [1, 3, 4.2, 22, 1.33, undefined, 21, 4, 3];

..and an array of objects containing some songs along with my rating of each of them, nestedData:


const nestedData = [{
  rating: 5,
  song: 'Song 2'
 }, {
  rating: 4,
  name: 'Top Man'
 }, {
  rating: 4.5,
  name: 'Clover Over Dover'
 }, {
  rating: 3,
  name: 'Pressure On Julian'
 }, {
  rating: 4,
  name: 'Yuko And Hiro'
 }
];

`d3.min()`

Use it to find the lowest value inside an array.
Js provides a Math.min() operator but d3.min() will prove more flexible and forgiving, for example when our dataset is an array with holes (some positions have null or undefined value, just like our data array). In our case, here are the results:

const dataMin = d3.min(data); // => 1
const nestedMin = d3.min(nestedData, item => item.rating); // => 3

Let’s compare the Js, no-lib version of the same code:

const dataMin = Math.min.apply(null, data); // => NaN :(
const nestedMin = Math.min.apply(
null,
nestedData.map(item => item.rating)); // => 3

In the first case we are bitten by the sparse array, in the second we go through a certain degree of verbosity. The d3 versions are certainly safer, terser and more compact. Of course, we can cater for this particular case and fix the nasty NaN returned by the first method:

const dataMin = Math.min.apply(
null,
data.filter(item => typeof item !== 'undefined')); // => 1

The implementation of d3.min can be found here. Read the next method for some common considerations about its usage in D3.

`d3.max()`

Use it to find the highest value inside an array.
Quite unsurprisingly max is the opposite of the min method. The very same apply, so using it with our two arrays is just as easy as this:

const dataMax = d3.max(data); // => 22
const nestedMax = d3.max(nestedData, item => item.rating); // => 5

The implementation of d3.max can be found here. Again, this method does not count undefined and null values, and it will safely skip over them. It will compute strings though, as we’ll see in a short while.

Just for fun I tried throwing a bit of everything to 'd3.max' and its diminutive counterpart 'd3.min'. Some (pointless?) tests include:

d3.min(); // TypeError :(
d3.min(1); // undefined, make sure you pass an array!
d3.min(1, 2); // undefined, make sure you pass an array!
d3.min(null); // undefined
d3.min(['', 1, 2]); // => '' <= watch out for this one
d3.max(['', 1, 2]); // => 2
d3.min(['hey ho!', 1, 2]); // hey ho!
d3.max(['hey ho!', 1, 2]); // hey ho!

The biggest thing here — apart from the suggestion to make sensible datasets (i.e. do not copy the ones above) — is to be wary of empty values stored as empty strings as they are picked up and compared. Not that it’s that frequent, but anyway it’s good to know.
Comparing strings can actually be way more useful, though. We can for example find the darkest colour within a set.

d3.min(['#15234C', '#5a5f6d', '#183b9e', '#3d9e18']); // "#15234C"

A practical example for this could be having a palette of colours and deciding to plot our data using the darkest colour as upper bound and the lightest as lowest bound. This will allow us to very easily create ranges of colours for our data visualisations.

This is a very powerful feature, and if you're interested in a practical use of it, do check out my post on Interpolating colours within a range in d3.js.

`d3.extent()`

Use it to find the lowest and the highest values in one function call. Returns an array.
Finding min and max values in an array is such a common operation in D3 that such functionality is grouped into one convenience method, extent.
Let's try it.

d3.extent(data); // [1, 22]
d3.extent(nestedData, item => item.rating); // [3, 5]

This is exactly the same as the following code, but more concise:

const dataExt = [d3.min(data), d3.max(data)]; // [1, 22]

With extent we are calling only one method rather than two. I thought that under the hood, extent was just a wrapper around min and max. It’s not.
Arguably the most natural usage for extent is when calculating ranges and domain of our datasets, where we normally have to provide a minimum and a maximum number for computing a scale.

`d3.sum()`

Use it to get a sum of all the elements of an array;

Again, as expected, it skips over null and undefined elements.

d3.sum(data); // 59.53
d3.sum(nestedData, item => item.rating); // 20.5

This can be achieved quite easily with vanilla Js and reduce, but failing to check for null or undefined elements will spoil the party.

data.reduce((acc, item) => acc + item, 0); // => NaN :(
nestedData.reduce((acc, item) => acc + item.rating, 0); // 20.5

`d3.mean()` and `d3.median()`

Use them to find the mean and median values of an array.

We close today's overview with two very related methods, mean and median.
The meaning of mean and median can be easily mixed up, so I put these methods together in order to start with an explanation of their differences. Both concepts represent the average of a dataset, or better, the central tendency of a set of statistical scores.

The mean is the most widely understood and common expression of an average. It is calculated through the sum of all elements in the dataset divided by the number of them, or - translating this to Js - t*he sum of the items of the array, divided by its length*.

To give an example let’s create a new array for this purpose.

const arr = [1,2,3,4,5,8,10];
let sum = arr.reduce((acc, i) => acc + i, 0);
sum / arr.length // 4.714285714285714

The median is instead that number that sits in the middle of our dataset. Our median will be the value where half of the items will be sitting before it, and the other half of the values will come after it.

There’s no easy mathematical formula for calculating the median. Hence, calculating its value for a dataset without any library is going to be a tougher challenge, more so because we have to account for different behaviours when our dataset length is even and when our dataset length is odd.

Given this sorted array:

const data1 = [1,2,3,4,5];
// ----------------^

Our median will be 3, as that is the value that sits in the middle “splitting” the array in two halves.

In this case though:

const data2 = [1,2,3,4,5,6];
// -----------------^ uhm... 3 or 4?

There’s not a single value splitting the array, so we can say that both 3 and 4 sit in the middle. To find the median in this case we have to sum these 2 values and divide by 2 (that is, we will apply the formula we used to find the mean). Our median in this case is 3.5.
Luckily D3 has this functionality built in, and we can leave the library do the math for us.

So, going back to our original datasets we can find mean and median very quickly.

d3.mean(data); // 7.44125
d3.median(data); // 3.5
d3.mean(nestedData, i => i.rating); // 4.1
d3.median(nestedData, i => i.rating); // 4

The results above highlight a very interesting case. While the difference between mean and median of our set of songs is negligible (4.1 and 4), we can’t say the same when doing the same computations for our list of numbers. Why is that?

The reason is that the mean is easily influenced by spikes in the dataset. One single very low or very high value can easily skew our result by a significant amount. The median, instead, will not follow the same destiny, giving us an arguably more accurate idea of where the mid point is and what the central tendency actually looks like.

To illustrate this, let’s add one value to our previous array and test it out again with the help of d3:

const data3 = [1,2,3,4,5,1500000];
d3.mean(data3); // 250002.5
d3.median(data3); // 3.5

Now it’s very clear how a subtle difference between the two concepts may actually translate to striking differences in real world scenarios.
This means that when we need to represent the average of a dataset we first of all have to understand “which average” we want our users to see, or which one is more meaningful when telling our story through a visualisation.

There’s no single answer to this question and that’s a very good reason to have well clear in mind what exactly are the purposes of these two apparently similar methods that D3 provides.

This is just a small part of methods that d3 provides to act on arrays and maps, and certainly the ones I use the most. Many more are exported though, as you can see from the source code, and it's good to know that there might be a function in there that is tailored to our needs.

Credits

Cover picture is by ShareGrid.

Originally published on my blog.

Vs Code one tip a week: splitting panes

Aurelio — Thu, 01 Aug 2019 09:22:23 +0000

It's quite common when coding to have the need to view multiple files at once on the screen. At times, we might even want to view two different parts of the same long file. Other times again we just want to make the most of a widescreen monitor.

For all those case splitting our editor is the solution, and today we'll see how to do it without the help of a mouse.

Split editor to the right (vertically):

Mac - ⌘ + \

Win - Ctrl + \

Linux - Ctrl + \

I try to commit to memory this shortcut by associating the (back)slash with the idea of cutting/splitting something in a half. Not sure it makes sense, but it does work for me!

An editor can also be split horizontally (or, as in VsCode lingo, orthogonally). I don't use this shortcut but in case you have different habits here it is:

Mac - ⌘ + K + \

Win - Ctrl + K + \

Linux - Ctrl + K + \

Even more ways to split the screen

If you pull up the command palette (⌘ + SHIFT + P on a Mac, Ctrl + SHIFT + P elsewhere) you will see some other options to split the screen, such as Split Editor Down, Split Editor Left etc.

These have no associated default key binding and can be accessed via the palette. If you feel you want to have them available as a shortcut, you can use VsCode key shortcut editor to add your custom key combination.

Credits

Cover image is by Drew Beamer. Check out his work here.

This is an effort to learn how to get the best out of Vs Code keyboard shortcuts without feeling overwhelmed.

Learning how to use our favourite IDE without a mouse can make a big difference.
Since an extension like the amazing Key Promoter for Jetbrains seems to be far from being a reality for now at least, I started collecting my favourite keyboard tricks in bite sized chunks.

The idea is simple: find one tip you like, practice it the whole week until you've really mastered it and made it part of your workflow and then move to the next one. Follow me and improve together!

Originally published on my blog.

Forem: Aurelio

Lunch break talks #2: Things I wish I knew when I was younger

"See the bagel"

Perspective matters

Give yourself to your team members selflessly

Listen first, speak last

Don't panic

"We all deserve a styrofoam cup"

The #1 ingredient of a successful team

The recipe of a great team

Let's stand on the shoulders of giants and look for the answer

What is Psychological Safety and why does it matter?

The traits of a psychologically safe environment

What Psychological Safety is not

How does Psychological Safety exist within a team?

Who should invest in Psychological Safety?

Looking back: an interesting game

Should my small team really, really, really do code reviews?

When you shouldn't do code reviews

Let's talk about code quality

What to review

But, but... this slows me down!

How thorough should your reviews be?

Who should be assigned to reviews?

One extra tip: comment your own PRs

In short

How I remember everything I learn

What I tried

An impossible balance

Turning point

Evolution

Giving it a try

$ considered harmful

Disclaimer

Problem

What does $ even mean

Why you should not remove $

The case for removing $

How to remove $

The easy way

The stylish way

Should you really stop using $?

D3: a JS library for the next 10 years?

Some history

The Present

6 reasons for the long-lasting success of D3

Stable

Thoroughly tested

Bug free

Actively maintained

Modular build

Philosophy

Conclusion

Lunch break talks #1: Simplicity is complicated

New features

Complexity

Readability

Simplicity

Working with environments in Postman

Life without Postman environments

Learn how to work with environments

Getting more out of Postman environments

Why I stopped spreading props on React Components

I stopped spreading props... but not quite

Beautiful is better than ugly.

In the face of ambiguity, refuse the temptation to guess.

Explicit is better than implicit.

References

Compound scales in D3.js

Credits

Array methods in D3.js

Installing and using the module the right way

d3.min()

d3.max()

d3.extent()

d3.sum()

d3.mean() and d3.median()

Credits

Vs Code one tip a week: splitting panes

Even more ways to split the screen

What does `$` even mean

Why you should not remove `$`

The case for removing `$`

How to remove `$`

`d3.min()`

`d3.max()`

`d3.extent()`

`d3.sum()`

`d3.mean()` and `d3.median()`