Forem: Wes Souza

'B' is assignable to the constraint of type 'T', but 'T' could be instantiated with a different subtype of constraint 'A'.

Wes Souza — Sun, 15 Jan 2023 21:23:12 +0000

This error has plagued me for years now. And thanks to Inigo I finally understood the problem.

TL;DR: When you use T extends A in a generic declaration, you require T to be at least A, but it can have more properties (by being a different subtype).

The problem arises when you want to create an object that conforms to T thinking it can just conform to A. You can't, because T can require additional or more specific properties than A.

This happens a lot when we create React Hooks that handle generic objects and arrays.

One solution is to pass a callback function to the generic that knows how to translate something like A to T, given what your generic function expects to handle.

The Code

Suppose we are creating a hook to abstract filtering options for a combobox, having a disabled "No results found" option if there is no result for the search:

type SelectOption = {
  name: string;
  value: string | null;
  icon?: string;
  description?: string;
  disabled?: boolean;
};

function useComboboxFilter<T extends SelectOption>(props: {
  options: T[];
  filterValue: string;
}): { filteredOptions: T[] } {
  let filteredOptions = props.filterValue
    ? props.options.filter((option) => option.name.includes(props.filterValue))
    : props.options;

  if (props.filterValue && !filteredOptions.length) {
    filteredOptions = [
      { name: "No results found", value: null, disabled: true },
    ];
  }

  return { filteredOptions };
}

Note for React devs
Because this is an example, I didn't properly optimize the code. A proper React Hook should wrap filteredOptions and the return object in a useMemo:

function useComboboxFilter<T extends SelectOption>(props: {
  options: T[];
  filterValue: string;
}): { filteredOptions: T[] } {
  const filteredOptions = useMemo(() => {
    let filteredOptions = props.filterValue
      ? props.options.filter((option) =>
          option.name.includes(props.filterValue)
        )
      : props.options;

    if (props.filterValue && !filteredOptions.length) {
      filteredOptions = [
        { name: "No results found", value: null, disabled: true },
      ];
    }

    return filteredOptions;
  }, [props.filterValue, props.options]);

  return useMemo(() => ({ filteredOptions }), [filteredOptions]);
}

The Problem

If you check this code with the TypeScript compiler, you will get this error:

Type '{ name: string; value: null; disabled: true; }'
is not assignable to type 'T'.
  '{ name: string; value: null; disabled: true; }' is 
  assignable to the constraint of type 'T', but 'T' could
  be instantiated with a different subtype of constraint
  'SelectOption'. ts(2322)

This is a cryptic error message: it properly describes the problem without helping the reader understand how this happened or what they actually did wrong.

The problem here is quite simple: { name: string; value: null; disabled: true; } satisfies SelectOption, but because T could be a different subtype of SelectOption, that is, a type with slightly different requirements, your generic function can't know what it is to create a new version of it.

A clear problem for our example is: imagine the generic type T we created requires an id property:

type SelectOptionWithId = {
  id: string;
} & SelectOption;

const myFilter = useComboboxFilter<SelectOptionWithId>({
  options: [],
  filterValue: "bla",
});

The result myFilter in this case will have an object without id, because the generic hook doesn't know it needs to add that property.

Because the generic code doesn't know T, you can only create a new version of SelectOption. To fix this, you need a way to transform a SelectOption object into T, which only your non-generic code can provide.

One Solution

Because inside useComboboxFilter you only know about SelectOption, and you only care about the name, value and disabled properties of it, you can create a required function parameter that translate a partial SelectOption into any T:

function useComboboxFilter<T extends SelectOption>(props: {
  options: T[];
  createOption: (
    option: Pick<SelectOption, "name" | "value" | "disabled">
  ) => T;
  filterValue: string;
}): { filteredOptions: T[] } {
  let filteredOptions = props.filterValue
    ? props.options.filter((option) => option.name.includes(props.filterValue))
    : props.options;

  if (props.filterValue && !filteredOptions.length) {
    filteredOptions = [
      props.createOption({
        name: "No results found",
        value: null,
        disabled: true,
      }),
    ];
  }

  return { filteredOptions };
}

The error is gone!

When you then use your generic useComboboxFilter with a subtype of SelectOption, you must make sure the generic function can create a new object that satisfies that type:

type SelectOptionWithId = {
  id: string;
} & SelectOption;

const createOption = (option: SelectOption): SelectOptionWithId => ({
  id: Math.random().toString(),
  ...option,
});

const myFilter = useComboboxFilter({
  options: [],
  createOption,
  filterValue: "bla",
});

Note that with the createOption property, TypeScript infers SelectOptionWithId for myFilter.

If you want to learn more about generics and other neat TypeScript features, be sure to check @mattpocockuk's YouTube videos and his Total TypeScript online course.

The Next Twitter

Wes Souza — Sun, 20 Nov 2022 23:50:59 +0000

The world is not happy with Twitter. Lots of really bad decisions are being pushed by its arrogant new leadership, both in a hurry and in public. This it a unique opportunity to witness what bad management can do to teams and products on an entire company scale.

Twitter has been, for better or worse, the world’s most public megaphone. It is where we as a collective go vent, broadcast, and have meaningful conversations with all sorts of people, all in the open.

The web never lacked good platforms for communication. Long before Twitter a multitude of self hosted platforms helped communities flourish, keep in touch, and share knowledge. Forums, Reddit, heck even mailing lists are still used as public hosts of community discourse.

What made Twitter unique, in my perspective, was twofold: there was a limit, and it was all public.

People Want Less

If there is a societal trend today, it is short-form content presented in an infinite collection. People don’t need to invest their time reading a long article or watching a long video. They can easily glance at a piece of text, image or video and decide if it is worth consuming or skipping to the next one. ^[1]

Twitter limited us to 140 characters. Instagram photos have always been 1080 pixels wide. Vine videos couldn’t be longer than 6.5 seconds, and TikTok once limited them to 1 minute.

These limitations not only help us judge if the content deserves attention, it makes content very easy to produce.

Platforms can then evolve and have the first post as an introduction for more. A very common practice on Twitter is appending “A thread 🧵👇” at the end of the first tweet in a series of replies, where authors entice people to dive deeper into a subject. ^[2]

Threads were a natural evolution for the tweet limitation. On Instagram you can add multiple photos and videos in one post, and TikTok expanded video length up to 10 minutes long. Vine never did this, and it’s not around anymore.

People Want More

The platform, while still promoting brief content, must also be massive and entice the user’s sense of meaningful participation and potential to grow.

Twitter gives everyone an opportunity to write anything that can go viral. Posts are public, searchable and open to anyone’s reaction by default. Even if the majority of user content isn’t amplified, the potential that it can motivate people to write and engage more by retweeting and replying.

This broadcast characteristic also attracts famous people to join the platform and bring their content and opinions, giving yet another reason for more people to engage. Large accounts can reach millions of people for free, and the common folk gets a direct communication channel. ^[3]

But Wait, There’s More

While I do believe that Twitter’s success can be associated with those two pillars, it is undenyable that many other factors played significant roles for the company to become as relevant as it is today.

Twitter has been around for a very long time. It evolved very slowly, making careful product decisions^[4]. It attracted many big players: artists, companies, governments. Its web and mobile apps are very user friendly and responsive. Its infrastructure got extremely reliable handling the immense amount of generated content. It became so mainstream it borrowed the “@“ from email to itself.

Most of these are chicken-and-egg scenarios. It might take years for your product to actually find its place in history. You can’t build it and expect success without important users, which might not be there at frist. You shouldn’t invest in infrastructure when you don’t need it.

What one can do from the start, and hopefully for the lifetime of the company, is invest in good product decisions and user experiences. Needless to say, evidence shows Twitter completely abandoned the former.

The Next Twitter

To me, The Next Twitter includes all of the above. It needs to provide a good amount of short-form content that can be expanded, important users that can raise engagement and bring more users to the platform, the best user experience possible on both the web and mobile devices, and good people making decisions guided by their users and their vision, not their guts.

It might be the case that Twitter itself collapses, ressurects and becomes its next self. Only time will tell.

Cover image generated by OpenAI.

[1] To be clear here: I don't believe this is a good practice, but an abuse of our limited attention. Many aspects of social media products are not tailored to our wellbeing, but to making sure we engage and buy products.

[2] I also want point out that this might be the key difference between TikTok and YouTube. TikTok presents the TV channel experience: content already plays, and you are able to skip it and therefore tune the algorithm to offer you better videos. YouTube presents you a catalog of thumbnails and titles, which you then have to choose from.

[3] This phenomenon also applies to brands, where customer service is often much better via Twitter than traditional ways, such as phone calls.

[4] I feel this started to shift by the time they introduced Fleets. Many new smaller features started to appear and bloat the product surrounding the main timeline. Twitter has been completely musked today, and it is sad that product.

tRPC: Move Fast and Break Nothing – useReactNYC

Wes Souza — Sat, 05 Nov 2022 17:03:38 +0000

TypeScript is extremely popular nowadays but making sure the front end and back end speak the same schema is still a challenge. tRPC tries to help with that. In this talk, we're going to explore what tRPC is, how it compares with other solutions, and dive deep into a demo application showcasing its power to help keep types in sync on your entire application.

Recorded at a useReactNYC meetup on August 2022.

Simple React State Management

Wes Souza — Tue, 30 Jun 2020 17:39:55 +0000

A good state system aims to be concise, easy to scale, and easy to debug. State is very unique per project, so a "one size fits all" framework is very unlikely to ever exist. Redux, MobX, XState, Apollo and Relay are some great frameworks, but they all have compromises.

Instead of utilizing a framework, we can use small libraries and apply strong concepts to guide our own code. The result is a robust and easy to debug codebase. Pure JavaScript.

Action Flow and Immutability

Two concepts that go hand in hand are action flow and immutability. Actions are the only place where the state is allowed to mutate - which helps to keep the state predictable. When mutating the state, we always replace object references with new ones instead of altering the original object, preventing side effects on methods that already are operating with the data elsewhere.

Immer is a small library that helps us write object manipulations that look like traditional code, but preserve the original state of the object. Here's an example of an action updating state using Immer:

import produce from "immer";

let state = {
  isLoggedIn: false,
};

async function authenticateUser(username, password) {
  const { error, user } = await api.loginUser({ username, password });
  if (!error && user) {
    state = produce((stateDraft) => {
      stateDraft.isLoggedIn = true;
    });
  }
}

The produce function takes a callback that receives a draft version of the object we want to mutate. Every operation inside of the callback is applied to the draft, preserving the original object state.

We then update the reference to that object so that future references retrieve new data.

We can build a library that wraps produce, and helps us create new state objects and emits an event whenever there is a mutation. Other parts of our software can then be aware of that change and react accordingly.

You can take a look at an example on the StateManager.ts file.

Portability by Separation of Concerns

The separation of concerns principle helps the state stay concise on its operations. The goal is to allow developers to understand and alter it with little effort. We can group files that are relative to a specific concern, such as "authentication". Only those files are allowed to read from and write to that part of the state object.

This centralizes the manipulation of that part of the state in one place, and any changes happen very close to each other. This reduces the cognitive load and keeps the code organized.

Here's an example file structure for an authentication flow:

/src/state
  |- /authentication/actions.js .... Log in, log out, forgot password,
  |                                  calls fetch user after login
  |- /authentication/selectors.js .. Is the user logged in?
  '- /user/actions.js .............. Fetch user, uses authentication
                                     selector

Hooks

Hooks allows us to subscribe to the mutation events the state machine emits, using useEffect for the event subscription and useState to handle new renders.

Referencing our StateManager.ts example from before, combined with hooks/useSelector.ts, we can read and mutate our state with ease:

import { userLogout } from "state/user/actions";
import { getUser } from "state/user/selectors";
import { userStore } from "state/user/store";

export function UserWelcome() {
  const user = useSelector(userStore, getUser);

  if (!user) {
    return 'Not logged in.';
  }

  return (
    <>
      <div>Hello {user.name}!</div>
      <button onClick={userLogout}>Logout</button>
    </>
  );
}

You can read more about it at my WesSouza/immer-state reference repository, which contains a simple proof of concept for this system.

Writing Good Pull Requests: A Primer

Wes Souza — Tue, 18 Feb 2020 23:00:00 +0000

Pull Requests are the main path to add code to any open source project, as well as many closed source ones. They are opportunities to add new features, fix bugs, or bring improvements to the quality of the project.

Before contributing to a project, it’s important to pay careful attention to its contribution rules. An ideal pull request has a clear title, a concise body, and well-defined commits. Below are some suggestions for opening a good pull request for any type of project.

Read the Contributing.md File

Before anything, it is important to understand the contribution rules. What is the expected code style? Should you rebase commits from master before pushing, or should you merge your branch[1]? How are the commit messages formatted? These and other rules are often laid out in a document named CONTRIBUTING.md, on the root folder of the project, or in a docs folder.

Read the document thoroughly and follow its guidelines.

Scope of Work

Make sure your pull request refers to a single scope of work, one clear goal. This will make it easier to follow and reason about.

If you are fixing three bugs, it’s better to open three isolated pull requests. PRs that depend on each other are a bit more complicated[2].

Commits

Commits are how Git keeps track of code history. For a pull request, the most important aspect of a commit is to isolate part of your change so it has a smaller, more manageable cognitive load. This only applies to larger pull requests, and can vary a lot.

You can see it as a recipe, where you break your work down into smaller pieces.

Let’s consider an example: you need to fix a bug in a library function in the code, by introducing a new required parameter to it. That function is used in many places in the codebase, which will also need to change to work with the new function signature. You will also want to update the function’s tests, to make sure that parameter works as intended.

We can split this up into two separate commits:

Update the library function including a new parameter;
Update the code to adhere to the changed function signature.

This way, a person reading the pull request can separate what changed as part of what step on your recipe, and verify each step independently.

If we mix the steps, it might be easy to miss the changes in the library among its use changes.

Commit Messages

Every commit message on your branch is important to understand what the commit changed. First of all, check the contribution guidelines for instructions on how to format and phrase the commit messages. Some projects use a rebase and fast-forward merge strategy, which means your commit messages will go as-is to the master branch.

If the rules on the branch commit messages are open, make sure to keep them aligned with the guidelines. Most guidelines ask the message to be short, in the present tense, imperative mood, and not end with punctuation.

In our example:

Fix binaryToString not working, introduce encoding parameter
Update usage of binaryToString across the code

See how we’ve used "update" instead of "updated" or "updating". This makes the messages more uniform, and usually shorter.

Pull Request Title

Your pull request title is how other people will find your contribution. It represents the main intent of your proposed changes, so it should represent it well. Try to apply the same guides from the commit messages into the PR title.

You can highlight side-effects of your change can in the body instead, to keep the title concise. In our example, we can use:

Fix binaryToString not working

This title highlights the intent of the pull request. The code contained in this pull request is all related to achieving this goal.

Pull Request Body

The pull request body is your opportunity to have a conversation with the reviewers. Describe your changes and reasoning in detail, and match the commits with the proposed change explanation.

It is where you can argue about decisions you took to achieve the proposed change in the title. It can also be a place to mention alternatives you didn’t take or would be willing to take if requested.

My ideal pull request body has the following structure:

A paragraph describing the main changes in detail
A list of steps taken to achieve those changes
Considerations about the approach taken and other available options
Linked external resources

The first item is mandatory, the remaining ones are optional. They depend on the extent of your changes. Use your best judgement.

Sometimes extra assets can make a huge difference. If there is a visual change, add a screen capture or video that highlights the changes. It is a great way to convey the effects of the changes.

In our example, we could say:

This fixes all cases where `binaryToString` stopped fooing, by making explicit
the need of the necessary encoding. 

It:
- Fixes `binaryToString`, and adds a new encoding parameter
- Updates usage of `binaryToString` across the code to pass the correct encoding
  parameter

`binaryToString` used to infer the encoding, which used an unsupported
feature[1] that was unsafe and caused problems in some situations[2]. In order
to avoid the issue, we will stop inferring the encoding and instead require it
to be passed down.

1: https://example.org/encoding-detection
2: https://example.org/issues-with-encoding
Jira: ABC-123

Here we are free to write the text on any form, as long as it’s concise and reasonable to the reviewer.

You should remember that we are speaking to another person who is seeing that change for the first time. We must be careful to not make assumptions about the reader’s knowledge of the matter, by always providing enough context.

Writing a perfect pull request is not possible, but we can make efforts to write ones that are as good as possible. Some key takeaways are:

Always follow the contributing guidelines;
Limit the affected scope so your intent is clear;
Be concise on your text and commit intent;
Provide context about your decisions;
Detail alternatives and visual examples of the changes, if possible.

Remember: reviewers are people. They are trying to understand your point. They might not have as much knowledge as you about your intents.

I hope this helps you make sure your pull request gets approved and merged in no time!

There isn’t a standard way on git to point out that one branch depends on another. You can open multiple PRs where they all have the commits they are dependent on, which might be confusing for reviewers since those changes are not described by that PR; or open PRs that are merging your code into a parent PR branch instead of master, but remember those branches are not protected, so restrictions might not apply. This is, for sure, a topic for an entire new article.

Thanks to Daniel Fosco, Jay Ashe and Mathias Jessen for the help revising this content.
Photo by Ross Findon on Unsplash.

Bringing Components to Legacy Code

Wes Souza — Mon, 01 Jul 2019 23:49:54 +0000

Not all systems allow the code to take over the entire rendering of your app. Sometimes you want to modernize and scale your code using libraries such as React on systems that already have a lot of legacy interactive code, or a CMS that must controls what is rendered in the page.

This talk shows techniques to adopt an existing environment so modern libraries can coexist with existing environments, where the DOM dictates the components it needs.

Recorded at a ReactNYC meetup on September 2017.

Web developers: with SwiftUI, would you consider learning Swift?

Wes Souza — Mon, 03 Jun 2019 19:41:49 +0000

Apple just announced SwiftUI, a "simple way to build user interfaces across all Apple platforms with the power of Swift".

It's a declarative way to create native views. It's very similar to component systems such as React and Flutter.

Are you curious about it? Would you consider jumping into native development?

What if they release a version for the web?

Edit: Changed title to reflect "learning Swift" instead of moving to Apple's iOS platform. Cross-platform is also diversity.

Why I Became, and still am, a Web Developer

Wes Souza — Thu, 30 May 2019 20:05:32 +0000

Once upon a time, my young self opened Notepad, entered many characters, saved as an .html file, opened it on Internet Explorer, and saw magic happen. It was life-changing.

Eighteen years later, and I'm making a living out of the same principles. HTML, CSS and JavaScript. Working for a product agency with amazing clients. Building native mobile apps, front-end websites, back-end systems. Living in the city I always dreamed of.

Hello World

When I was 15 years old, I got internet access at home. Dial-up, something around 40 kilobits per second. That's five KiB per second. That was what was available in my town at that time.

There was no Firefox. Google was barely a search engine (I'm from Brazil, we used another search "engine" at that time). There was only Internet Explorer and Netscape Navigator. And websites were always "best viewed on Internet Explorer", so it was what I used.

I then took a computer introduction course, one that taught "professional computer skills" like Windows 98 and Office 97. And the last book was "web". We barely got to start it and the course was over, but it intrigued me.

It was easy to create documents, style them, and – most importantly – add behavior to them.

Fast Learning Curve

To get started with web development, one needs only a text editor and a web browser. All popular operating systems come preinstalled with both. And you don't need to compile the code, just save and run.

The syntaxes involved are also not very cryptic.

<button style="background: purple" onclick="alert('Hello!')">
  Say Hello!
</button>

There's much more complexity to all of them, but it's undeniable that with a few concepts, and a few lines of code, anyone can create something already very robust, if compared to other platforms.

On a native platform, in general, you often need to download an IDE and a compiler, then write code for the behavior, use a visual editor for the visual interface, and write bindings between both. Then you need to compile and run.

"I Made Something!"

The friendlier the entry point of a technology is, the more people feel comfortable experimenting with it. And if you can use that technology to build something that works, the experience is extremely satisfying.

Given the fast learn curve of web development, and the fact that the tools are simple and readily available, it's not a surprise that JavaScript, HTML and CSS are the most popular languages in the development community nowadays.

And regardless if it's a quirky terminal emulator, or a very useful nearby subway time table, it's always fun to see your creations come to life.

"I'm Learning!"

The web is not just a set of rules to create, style, add behavior to, and link documents (although it started as one). It provides numerous tools so creators can produce a myriad of complex user experiences, from a website with comments, to an entire social network.

All of this involves an extensive list of APIs that allow web browsers to transform text files into rich experiences such as playing videos, making music, capturing the user's webcam, and much more.

All of this is not only standardized, but also continuously changing through developments by its working group bodies: W3C, WHATWG and Ecma TC39.

Because of that, you can choose to become a specialist on many very different realms. For example, you can dedicate time to learn about accessibility, which is an increasingly important pillar of software development today.

"I'm Meeting Great People!"

One of the most fascinating things to me is how friendly, inclusive and supportive the web development community can be. There are a huge number of local meetups all over the world, great conferences that span across a number of topics.

One recent example was ReactJS Girls, a conference focused on React development that had only women speakers. Diversity has been a big problem for the software development industry, where 92% of surveyed developers on StackOverflow identify as men in 2019.

The conference idea was to showcase women talent, and it delivered. It was extremely fun, full of great, entertaining and informative talks, and met many great developers there, from all over the world.

You can watch all the talks at YLD's YouTube channel, and if you're into React development (or any component-based system), Jenn Creighton's The How and Why of Flexible React Components is a must-watch.

But, as in any group, there are Hundreds of Niche places where you can find angry, aggressive developers that prefer to insult rather than help. But let's not focus on them.

Moving Forward

Find your passion. Find the passion inside your passion. And keep improving.

My specialties are software architecture and state management. I really enjoy an organized codebase that allows people to easily move around areas they're not familiar with and be able to easily add to them. I also really like to understand a product's business rules inside and out and apply them to the state management of the app in a robust way.

But there are multiple different areas in the web that span knowledge across all of HTML, CSS and JavaScript. You can become an expert in animation, DOM manipulation, a certain framework or library, accessibility, unit or automation testing, continuous integration and delivery, and much, much more.

That's why I really recommend finding yourself a mentor. Other places you can look for mentors are the DEV Community and Coding Coach.

I love the web because it's welcoming, inclusive, and fun. And there's always something new to learn on it.

If you want to reach me, my DMs on Twitter and DEV are always open.

how2: Using GPG on macOS without GPGTools

Wes Souza — Tue, 15 Jan 2019 16:16:21 +0000

I don’t like GPGTools. I want GPG on macOS. Every tutorial has some obsolete part. Here’s what I did.

GPGTools installs a lot of things that I don’t want to use. I just want to sign my commits on GitHub and save my GPG key in macOS keychain.

There are two main dependencies to achieve that, gnupg contains the GPG tools to generate keys and sign things, as well as an agent to do agent things; and pinentry-mac which is the part of GPGTools that prompts for your key password and stores it on the OS keychain.

GPG Setup

Before anything, install Homebrew.

After that, install the dependencies:

brew install gnupg pinentry-mac

Note the output of the install command, which will tell you the location of the pinentry-mac program:

==> Caveats
==> pinentry-mac
You can now set this as your pinentry program like

~/.gnupg/gpg-agent.conf
    pinentry-program /some/path/here

You need to configure gpg-agent to use pinentry-mac by creating a file ~/.gnupg/gpg-agent.conf, pointing to the correct pinentry-mac program:

# Connects gpg-agent to the OSX keychain via the brew-installed
# pinentry program from GPGtools. This is the OSX 'magic sauce',
# allowing the gpg key's passphrase to be stored in the login
# keychain, enabling automatic key signing.
pinentry-program /usr/local/bin/pinentry-mac

For Apple Silicon Macs, Homebrew uses a different path:

pinentry-program /opt/homebrew/bin/pinentry-mac

Then, let’s generate your first key. I recommend using RSA and RSA, a key size of 4096, and not having the key expire. Remember to choose a strong password.

gpg --full-generate-key

Then, sign a test message so pinentry-mac can store your password in the keychain:

echo "test" | gpg --clearsign

This should open a dialog prompting your password. Remember to check “Save in Keychain”.

Connecting to GitHub

First, copy your private key to add to GitHub:

gpg --export --armor your@email.here | pbcopy

And paste it in GitHub’s Settings > SSH and GPG keys > New GPG key.

Second, configure your git environment to use signed commits. I’ve done it globally. First obtain your public GPG keys:

$ gpg --list-secret-keys
(...)
sec   rsa2048 2019-01-15 [SC]
      YOUR_GPG_KEY_APPEARS_HERE
uid           [ultimate] Your Name <your@email.here>
ssb   rsa2048 2019-01-15 [E]

Then configure git:

git config --global commit.gpgsign true
git config --global user.signingkey YOUR_GPG_KEY

And finally, commit something with the-S argument to make sure it’s signed:

git commit -S -m "Testing GPG signature"

Troubleshooting

Things you can try if things are not working:

# Kill gpg-agent
killall gpg-agent

# Run gpg-agent in daemon mode
gpg-agent --daemon

Cover photo by Micah Williams on Unsplash.

Keeping Control of the Front-end

Wes Souza — Mon, 15 Feb 2016 08:00:00 +0000

At Booking.com, hundreds of developers and designers contribute daily to our codebase, which leads to potential complications with code discoverability, maintenance, and reuse. In this post, we’re going to focus on the client-side aspect of these challenges, and introduce some of the techniques we use to tackle them.

Prefixing and Namespacing

Because of the size of our codebase and the number of people introducing changes to it daily, it can be difficult to maintain unique identifiers for all of our pages’ components.

Both JavaScript and Cascading Style Sheets make use of identifiers to work properly, by means of variable names and selectors respectively, both on a global execution scope.

Let’s start with JavaScript. We make use of namespaces, which are object properties of a global variable. (We also implement modules, which will be discussed later in the article.)

// The only global variable
var B = {};

// The search namespace
B.search = {};

// Check-in date of the search
B.search.checkIn = new Date(2015, 3, 1);

// Travel purpose of the search
B.search.travelPurpose = 'business';

In the example above, B.search is the namespace we're using to visually identify our code. Notice how travelPurpose has its scope within search, clarifying its context and meaning.

CSS is different. Because CSS doesn’t provide a scalable way of grouping selectors, we make use of prefixes instead. We also make sure all selectors are as specific as possible — to prevent collisions. For example, in our files we already have about 4,000 class selectors containing the term item in their declaration.

Imagine the following simple case: a list of facilities on the hotel page.

<ul class="facilities">
  <li class="item">Wi-Fi</li>
  <li class="item">Breakfast</li>
</ul>

That might interfere with another team's work that is adding a universal menu on the website's header.

<ul class="menu">
  <li class="item">Home</li>
</ul>

On both cases, .item will have specific CSS rules that could be overridden, thus generating unexpected results. Sometimes these interactions happen on a specific page that was beyond the scope of the developer's tests.

To prevent these conflicts we often use prefixing:

<ul class="hp-facilities">
  <li class="hp-facilites__facility">Wi-Fi</li>
  <li class="hp-facilites__facility">Breakfast</li>
</ul>

Since we invest so much into experimentation through A/B testing, a considerable amount of code becomes irrelevant when its related experiment expires.

Because we want to avoid code rot in our codebase, we want to keep only the parts that we actually need, and those irrelevant pieces of code must be removed periodically. Being able to quickly search the code for a specific token, such as a CSS class name, is a key requirement for this clean up.

Control of Execution

It is very important that our JavaScript code runs in a controlled fashion. Our code needs to be precise by only executing when it is necessary for a certain feature, page, or event. It also needs to be robust, preventing interference between unrelated features.

Suppose we have three script files concatenated, and the resulting file is added to every page on our website.

// from tooltip.js
$('.tooltip').addTooltip();

// from available_rooms.js
var prices = $('#prices .price');
prices[0].scrollTop = 0;

// from sticky_user_bar.js
$(window).scroll(function () {
  $('.user_bar').css('top', document.body.scrollTop);
});

Any part that fails will prevent the next part from executing. For instance, if there is no element on the page that matches #prices .price there will be an error stopping everything else from executing, breaking the user bar behavior.

Also, there might be code that shouldn't be running, which is undesirable. In the example, if no element matches .user_bar on the page, the scrolling event is still monitored, wasting CPU cycles.

To mitigate this, we chose to develop an internal flow controller that provides an execution control API based on AMD, built on top of Almond. It uses setTimeout to provide a separate context, which then isolates failures and prevents the blockage of the main thread.

As a bonus, because the code is wrapped, we can easily label those calls for profiling and find features that might be wasting resources.

This also helps isolate the experimented part of our A/B testing, making it easy to find and clean up failed tentatives, as mentioned in the previous section.

Restricting Your Execution

While CSS code avoids clashes by using namespaces, JavaScript should not leak behavior to DOM elements or to other unrelated components in the same page.

Part of that problem can be prevented by following well-established coding principles, such as avoiding global variables (enforced by using the strict mode), modularizing the specific parts of your code, and so forth.

We also encourage our teams to develop context specific software to avoid side-effects.

$('form').on('submit', function () {
  var destination = $('.destination');
});

Here, every form element will have a submit event handler attached to it. Also, it searches the entire document DOM tree for the .destination selector, which might stop working as soon as someone inadvertently adds an element that matches the same selector.

An even better approach stresses specifying targets in more detail, aiming to only affect what needs to be affected.

$('.js-searchbox-form').on('submit', function (event) {
  var form = $(event.currentTarget);
  var destination = form.find('.js-destination-input');
});

In this scenario, the class names are clear and specific, and the code will only look for elements inside of its own form, preventing possible leaking.

Modularization

Having multiple teams working independently at the same time allows different development styles across the codebase. One developer might like wrapping her own code on IIFE, and another might prefer the prototype pattern.

While this is not a problem if the code is achieving a simple task, more complex solutions might become too big to understand, to manipulate, or to maintain.

function showTheGallery (hotelId) {
/* Here goes 31415 lines of code involving all event handlers, the overlay behind the gallery, capturing the keyboard events to navigate and close the gallery, logic to preload the images, logic to center the main image relative to another element, scrolling of the thumbnails, obtaining the images from a specific variable in the code, showing the gallery, etc. */
}

showTheGallery(42);

As you can see, parts of the code can become too complicated and isolated, making it difficult to understand and debug. It also prevents any kind of reusability.

However, we can break the code into smaller blocks that serve a specific purpose, as described in the DRY principle as "Every piece of knowledge must have a single, unambiguous, authoritative representation within a system".

define('photo-gallery',
  [
    'component-maker',
    'dom-position',
    'dom-scroll',
    'env-variables',
    'image-preload',
    'keyboard-events',
    'overlay'
  ],
  function (...) {
    // Tying them all together nicely, exporting an extensible component
  }
);

Here, every dependency is self-contained, specific enough, and totally reusable by others, and the resulting object allows quick extension and behavior changing, so the original code can be adapted.

Components

Following the principles of restricting the behavior of your code to exactly where you want it to run, and the fact that we want to build a modularized and reusable codebase, we developed a simple solution called B.components.

The principle behind it is to add behavior to one or more DOM nodes. It only executes the code when the element exists, and allows one component to extend the features of another, facilitating reusability.

<button type="button" data-component="alert">Alert</button>

In this example, we add behavior to a specific button in the code. The JavaScript doesn't need to know which exact element to target in the document, since it's the button that requests a behavior, not the other way around.

The code receives a pointer to the DOM node, and can perform the necessary action, such as listening to click events on this reference and triggering an alert window.

The benefit of this approach is its DOM-based flexibility. We might change every aspect of the HTML, and even add more elements, while preserving the same behavior.

<a data-component="alert">Alert Anchor</a>

<button type="button" data-component="alert">Alert Span</button>

We use AMD as the foundation to store the component definitions as modules, the same setTimeout technique mentioned before for containing the execution, and to create a new instance for each component definition found in the DOM or any specified node.

This solution frees us from knowing exactly what to do when rendering dynamic HTML on the page.

var templateCode = 'Complex HTML structure';
$('body').append(templateCode);

// We added tooltips, so initialize them
$('.tooltip').tooltip();

// We also added a lightbox, but that uses another API
LightboxFactory.addLightbox('#lightbox-a', { lightbox: 'options' });

// Did we forget something? Did some API change?

This is all replaced by a one-liner:

$(templateCode).appendTo('body').loadComponents();

The method $.fn.loadComponents will take care of finding the necessary components, and each component will be given the opportunity to initialize itself, all under the same predictable API.

The Big Picture

Because we are a big company with hundreds of developers, we exercise care so that our contributions leave our code better than we found it, keeping it more maintainable in the long run.

Organizing and namespacing our CSS and JavaScript blocks helps to make our code easily findable and robust. Controlling our executed code scope and only running it when really necessary makes it predictable and fast. Thinking about modules and UI components ensures we are able to quickly understand and reuse our solutions. All of this is done while keeping a good sense of community and respect for each other.

These are just some of the techniques we adopted and created at Booking.com to help us deal with the challenges of growth.

The important lesson is to always look a the big picture, never assume you are in a perfectly controlled environment.

Code must be resilient.

Small Things to Make Others Happy

Wes Souza — Sun, 01 Mar 2015 08:00:00 +0000

Working for a couple of big companies as MTV, Univision and Booking.com gave me a glimpse of what it is to deploy my code to a huge amount of users, and also share it with a lot of other developers and designers.

It made me learn a lot, and I’ve compiled this list of small positive actions that can potentially improve everyone’s daily routine.

Most of this makes more sense if applied in big organizations, due to the nature of having multiple people responsible for multiple aspects of a product or even multiple products.

Daily Life

The first part of the presentation revolves around common abstract ideas that I feel should be reinforced.

Keep Calm and Don’t Rush Your Commits

Rushed coding is a potential for undetected problems. Avoid rushing your commit just so that it makes the next deployment, from my experience nobody dies if your code is one day late.

Learn

Part of what makes us hackers is that we love to learn. And dealing with MSIE 8 is no excuse to stop in ECMAScript 3 and stop improving your knowledge.

It is also a good opportunity to expand your horizons. If you’re a designer with weak JavaScript coding abilities, seek training. Same thing for front end developers that do not code properly in their company’s back end language.

Teach

Knowledge should always be shared. Teaching makes you understand that subject better, because you only truly understand something if you can explain it to someone else.

Teaching improves your communication skills, spreads knowledge to your company’s community, and gives you karma points among your colleagues.

Embrace User Experience

Whenever creating a feature, do put the user in the center of your design. Do not solve using the quickest available solution, be it because of it being technically difficult, or just easier to couple with the current design.

From a design perspective this applies to every small enhancement that in the end culminates in a messed up visual experience. Because every new addition has to conform to the current design, and the first design was never conceptualized with all these new additions, the end experience is most of the times a mess. There are times to rethink the whole user experience.

From a developer perspective this applies to lazy solutions that work but do not make immediate sense to the user.

Your Code Is Not Yours

And by that I don’t mean your code is your company’s property. It is, don’t get me wrong, but my point is that your code is shared with a number of other developers and sometimes designers.

You have to be aware that you’ll hardly work in the same team forever, and that your software will certainly be changed and maintained by a number of different people throughout time.

And how many times you got back to your own code from the previous day and thought “what the fuck was I doing here?”

Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability. –John F. Woods

Keep it Simple

This is a mantra for every applicable aspect of your life. If you’re creating code, designing a new feature, talking about a new technology, creating a new database table, or even an entire new product, you should always aim for simplicity.

This goes together with code maintainability, because if you think into small, simple pieces instead of a huge chunk of interconnected functions you have more chances of having an understandable code file.

Value Others’ Opinions

Do not assume you have the best solution at all cases. This is part of life, but is greatly enhanced in technology, since we have to come up with solutions frequently, we tend to ignore others’ opinions and shove our solution down everybody’s throats.

Ponder what you are changing and involve people in your decisions before deploying your new code. Be it as a simple code review by a trusted colleague, or by an e-mail thread to the company’s developers list.

Engage in the Community

In big organizations, there is a huge chance that a lot of other people do the same kind of job that you do, and then it is your responsibility to gather together and talk.

This is extremely useful for sharing experiences, discussing new technologies, and determine technical steps — like moving to SCSS, using Browserify, implementing ES5 shims.

This also brings people together and engages people.

Code

Talking about more concrete things, these are my recommendations about HMTL, CSS and JavaScript coding.

Tabs vs. Spaces

I don’t care if you use tabs or spaces, but you must respect the current file settings. Set up your file editor to detect and use whatever the opened file has, and make sure you are not mixing up.

Specially when copying code.

<div>
     <a>
Drunk code.
 </a>
   </div>

Explain Your Code

We are not in 1980 anymore, your methods, variable and class names can be bigger and more descriptive. Other people must understand what your code does without reading extensive documentation or attending a workshop you give.

function wat(a) {  // what is a?
  let b = a.c;     // what is c?
  b += d.e;        // where the fuck did d come from?
  return !!b;      // oh dear.
}

Don’t Style #ids or elements

Styling ids are bad because they are technically unique for one element, and this restricts reuse of styling.

And big companies rarely have omnipresent design guidelines, so one <button> is potentially very different across components, so never style the element.

/* surprise interference! */
button { padding-left: 20px !important; }

Lower Your Specificity

In order to prevent a proliferation of !important shit, keep your CSS selectors specificity as low as possible.

This also reduces the chances of CSS interference between teams, since generic class names can be used at any time.

/* what the specificity hell */
body div#header ul.menu .item { }

/* hmm, peace */
.header-menu__item { }

Prefix

Whenever you create a new component, try to prefix every class name with it. The syntax becomes very verbose, which is actually good for consistency, self-explanatory code and small specificity.

/* component */
.searchbox { }

/* component + something */
.searchbox-input { }

/* parent component + state */
.searchbox.-active .searchbox-input { }

Template is Not Backend

Business logic and complex coding should be in the back end. If the template engine you use provide ways to program like ifs, loops, variable setting, never use them to create an algorithm in the template code.

It is always weird, hard to understand, and very fragile.

git diff is Our Friend

If you use git and have a master branch that is always deployable, you need to be very careful before pushing your code changes.

Doing a git diff before committing, or git show before pushing, gives you a last chance to see if you forgot to remove test code, or if there was a bad merge you need to fix, before breaking things for everyone else.

Conclusion

I hope you found something useful from these points. I know I would be much happier if everyone I work with followed them.

From Brazil to Amsterdam

Wes Souza — Wed, 28 Jan 2015 08:00:00 +0000

What I’ve learned after eight months living in the Netherlands

In this beginning of 2015 I commemorated the eighth month of my arrival in Amsterdam. I was found by a Booking.com recruiter on May of the previous year, and after three interviews, 33 hours in airplanes and the usual bureaucracy, immigrated to the Netherlands with a permanent contract.

I had never thought that I would be living in Amsterdam. If you know me, you’re well aware where my heart is.

Now, eight months later, I already go everywhere on my bike¹, fell miserably by getting both wheels on a tram track, smoked tolerated pot², saw a day with 16 hours of sunlight, had a barbecue on Vondelpark, took a lot of incredibly beautiful pictures, went on a road trip to Munich and Cologne, learned to play Tennis Table, met incredible people — some even became friends –, et cetera.

Panorama view from my first apartment in Jordaan

The good

Amsterdam is beautiful. It is a huge metropolitan city, with small and very tight historically preserved buildings, it feels cozy with nearby services — the same market every 2 blocks — but still full of big brand stores, tourists and life everywhere.

I was biking to work when it hit me: I really lik living here. It was a good weather, I was cycling peacefully, the landscape was gorgeous. There’s nowhere else in the world that combines all of this.

The tricky

The biggest challenge for people that come from warmer areas is the winter. It’s cold, it rains, and there are 80 Km/h winds, sometimes all together, because fuck you.

Customer service is also a pain point for most people. Here it’s normal to spend a lot of money on a 0900 customer call, only to get a condescending “sorry, I cannot help you at all”.

And don’t expect to learn Dutch so quickly. Besides being very difficult, 90% of the Dutch population speak English, and they often respond in English if they see you trying to speak poor Dutch.

The learnings

I am an expat, and expats are everywhere. The Dutch government is very open to accepting foreign people to live here. And this is partially explained by the shortage of IT workers in the country. There are a lot of expat specialized services, from the migration process to buying a house. And you get a ton of books and brochures to ease the transitions.

Everything can be very cheap or very expensive , for instance a good beer bottle costs around € 0,80 on the supermarket, but the rent of a small one bedroom apartment can be as high as € 1500. Overall that’s the only higher-than-normal expense, the rest is very reasonable.

Forget converting currencies because you’ll get insane. My Brazilian friends say “quem converte não se diverte”, something like “people that convert have no fun at all”, and that is true. It doesn’t make sense going back to your own country’s currency and comparing what you once spent there and here, you have to balance the absolute numbers, from your salary to your budget. And in the end you’ll see that things are surprisingly fair.

The city is not a mess of drunk and disorderly people. Although there are a lot of tourists, specially on the weekends, and drugs are tolerated², everything runs like clockwork. The city is constantly cleaned, public transportation is rarely crowded, and you rarely smell marijuana. The biggest mess happens on new years.

And people go crazy on new years. Seriously, it is the only period that fireworks are allowed, so people go nuts! I’ve seen them throwing firecrackers from apartment windows directly into walking people on the streets, lighting boxes of big explosives and watching very closely, kicking bottles with rockets that someone else left, making it fly into the crows at the Dam. It is terrifying and awesome at the same time.

Dutch people are born in their bicycles. Of course I’m kidding, but there’s no weather that can hold them back. They’ll be riding in heavy rain on a windy cold day, with an umbrella in a hand and a phone in the other. And they are above everything, if you’re a pedestrian, you’ll be screamed at for being in the way. And it helps a lot that the city is completely levelled. The biggest hills we have to cycle are some canal bridges, and the highest places in the country are actually shared with Belgium and Germany.

Parks. Parks everywhere. There are about 30 parks in Amsterdam, together with squares, a myriad of museums, night clubs and pubs, you’ll find something to do every time of the day.

It’s a great place for your children. Most of the Brazilians that moved here are married with young children, and it’s amazing how much their kids can learn, and how much the government is involved. From free health care and constant care monitoring, to the fact they’ll learn at least three languages (Dutch, English and their native), it is certainly a very good boilerplate for a world citizen.

And so much more

It’s impossible to resume everything in a post, it would be a book, and I bet many people already wrote one.

Ping me on Twitter or Facebook if you have suggestions for a complimentary post to this one.

And I can really vouch for Booking.com for recruiting and helping people move here. If you’re interested in working here, they have a lot of openings from frond end and back end developers, to data scientists, UX designers, and many other.

—

¹ Of course if the temperature is above 10˚C, and within a certain range.

² Nothing is really legal in the Netherlands, just tolerated.