Forem: Bhekani Khumalo

Why Svelte is Easy to Learn as a React Developer

Bhekani Khumalo — Mon, 23 May 2022 09:00:01 +0000

Originally published on the Offerzen Blog here.

Trying new frameworks is always a great learning experience. As a React developer, I used Svelte for a project and was really impressed by its out of the box features and the developer experience it provided. Heres why Svelte is a great framework to play with.

I started noticing a lot of tweets about using Googles advanced search parameters for better results. I realised that most people dont know about them and if they do, its not that intuitive to use them with minimal friction.

Thats why I decided to make Pro-Search, a UX-focussed, advanced search engine query builder. Pro-Search helps you find exactly what youre looking for by making it easy to add advanced search filters to different search engines.

Choosing the right technology for Pro-Search

To create Pro-Search, I ended up choosing SvelteKit, a framework that is to Svelte what NextJS is to React. Its an open-source web development framework that enables functionalities such as server-side rendering and static site generation.

At the time, I had never built anything with Svelte and I barely knew anything about it, so this was a bit of an odd choice for me as a React developer. Why did I use Svelte?

When choosing technologies, my top priorities were for it to:

Load fast: It had to load as fast as, or faster, than the most popular search engines (Google, DuckDuckGo, Bing, Yahoo).
Be simple: A search should be as simple and easy as on the search engine. Additionally, the building of those simple and intuitive UIs should be simple and frictionless as well.
Interactivity: The tech I chose should handle heavy interactivity easily.
Responsiveness: It was important that Id be able to create a progressive web app, and optimise for both web and mobile easily.

My goal was to create a great user interface while having an enjoyable developer experience, and Svelte delivers on both of these.

I chose Svelte because its fast, ships small bundles and provides many great features while staying very close to vanilla HTML, CSS and JS.

All these are possible because you dont ship Svelte with a Svelte app: its a framework without the framework. By statically analysing the component template ahead of time, Svelte ensures that the browser does as little work as possible.

Disclaimer: I will make many comparisons with React. I am not picking on React or saying Svelte is fundamentally better than React. React is the framework I know best so its easiest for me to draw comparisons from there.

What is Svelte?

Svelte is a frontend compiler for building interactive user interfaces similar to React and Vue. With most current popular frameworks like React and Vue, the browser must do extra work to convert declarative component structures into DOM operations at run time. This eats into the frame budget and taxes the garbage collector.

Svelte compiles your code into imperative client-side vanilla JavaScript that manipulates the DOM directly. This is done during a compile step that happens at build time. This means it can strip out the parts of the framework that your app doesnt use, resulting in a smaller bundle, fast first load and improved performance. Importantly, one of Sveltes selling points is that it avoids the overhead associated with runtime intermediate representations, such as the virtual DOM.

As a tool, Svelte is powerful, flexible and beautifully designed. Its compiler approach unlocks a broad range of capabilities making it ripe for further expansion and growth. Making things with Svelte feels fun and streamlined.

Lets walk through the developer experience and tooling and features.

Developer experience

Easy to learn

Svelte feels natural if youre used to HTML, CSS and JavaScript. This makes it easy to collaborate with people who have a basic understanding of CSS and HTML. If you know HTML and CSS, you can write Svelte immediately. You can then learn more as you go, layering new concepts on top of that.

Sure there are still many things that arent vanilla HTML, but theyre quite easily guessable once you see it done a few times. Being close to regular ole HTML also means it is a much easier onramp into using UI frameworks compared to React.

When it comes to docs, Svelte sets a very high bar for an unfunded project without people working full-time on it. Heres some of what Svelte provides in terms of docs:

I went through the Svelte tutorial in less than a day. It takes you through the concepts, incrementally increasing complexity and at each step and explaining why each thing exists. I found that this structure made it easier to stick with it. It also helps that theres a REPL thats structured to encourage you to keep trying what youre learning. By the time you finish reading the tutorial, youve already written quite a significant amount of Svelte, and youre familiar with the concepts and how it looks.

Everything out of the box

One of the first things I noticed with Svelte, especially coming from React, is that it comes with many essentials included out of the box. While React has tons of external libraries to extend it, its nice to work with a framework where I dont have to be making decisions at every turn about what to use.

To be fair to React, here are some things React has first-party that Svelte relies on external libraries for:

Abstracting the pain

Svelte has some nice syntactic sugar that makes the developer experience more pleasant. It clearly learnt a lot from its predecessors by abstracting away some of the pain.

For example, forms are a pain in React. Thats why libraries like Formik and React Hook Form exist. A form in React would look something like this:

import { useState } from 'react'
  const Form = () => {
  const [name, setName] = useState('')
  const handleChange = e => setName(e.target.value)
  const handleSubmit = e => {
    e.preventDefault()
    // some stuff here
  }
  return (
    <form onSubmit={handleSubmit}>
      <input type='text' value={name} onChange={handleChange} />
    </form>
  )
}

The same component in Svelte is:

<script>
  let name = ''
  const handleSubmit = () => {
    // some stuff here
  }
</script>
<form on:submit|preventDefault={handleSubmit}>
  <input type="text" bind:value />
</form>

The Svelte helpers and two-way binding are really handy because they make the code more terse and easy to follow.

State management

Pro-Search is basically many different UI elements that are used to manipulate the global state, and the Svelte stores made implementing this very easy. Given how much global state management I needed, using Svelte stores was much simpler compared to having to use Reacts context, redux and mobx.

Stores are JavaScript objects that adhere to a simple interface. With Svelte, a store is basically anything that has a subscribe method that returns a function, thereby allowing you to unsubscribe. Stores allow you to access data or functionality from multiple components. Theyll update your components whenever their data changes - hence that handy subscribe method.

Svelte stores allow for separation of the state management from the component hierarchy. This is important when the same piece of data is needed in more than one place.

This is how you create a Svelte store:

Import { writable } from 'svelte/store'
export const store = writable(0)

This is how you read and write to a Svelte store:

<script>
  import { store } from './store'
</script>
<button on:click={() => $store + 1}>{$store}</button>

Reactivity in the language

Svelte uses mutable variables for local states, and theyre reactive out of the box. This makes for leaner code. Heres a Svelte counter component:

<script>let i = 0</script>
<button on:click={() => i += 1}>count: {i}</button>

For comparison, heres the same thing in React:

import { useState } from 'react'
const Counter = () => {
  const [i, setI] = useState(0)
  return <button onClick={() => set(i + 1)}>count: {i}</button>
}

Svelte moves reactivity into the language by just using the language. Updating a value, and all the things that depend on it, is achieved simply by using the assignment operator (=).

<script>
  let count = 0;
  $: double = count * 2;
</script>
<button on:click={() => count += 1}>Double: {double}</button>

Since Svelte is a compiler, reactivity is achieved by just instrumenting the code behind the scenes:

count += 1; $$invalidate('count', count)

As you can see, this looks a lot like a regular HTML file. This, however, is also clever enough to know that whenever the value of the count variable changes, all the values that reference it will change as well.

Bad experience with testing

On the other hand, I havent yet found a good way to test Pro-Search. Given my history with React, I first reached for Jest and Svelte Testing Library. I spent several hours trying to debug with no success.

Then, I remembered that Cypress recently launched their component testing library. Again, I spent several hours trying to set it up and got many different errors until I gave up. After that, I was too frustrated but didnt want to kill my momentum so I parked the testing work.

However, I recently tweeted to ask the Svelte community what people are using and within minutes I had several responses with multiple resources. Im excited to try these out and see if I have better luck.

Svelte Tooling and features

Static Scoped Styling

Svelte comes with scoped CSS without using CSS-in-JS solutions: Its just CSS, no bells and whistles. Include a style tag in the component, write CSS and it will be scoped to the component by default: No configuration, just normal CSS. Of course, you can add the bells and whistles if you want to.

I have particularly loved working with Tailwind CSS, so this was the natural choice for me. Also: the configuration was a breeze.

Transitions and Animations

Before Svelte, I had never really worked with animations and transitions. Its always been something on my to-do list, but Ive never dedicated the time for it because it seems like a complex topic. Fortunately with Svelte, I didnt have to think about much: Straight out of the box, I just slapped on some pre-baked functions and it worked.

Small bundle, faster apps

One of Sveltes biggest strengths is its minimal JavaScript bundle sizes. This makes it ideal for any code that will be executed by low-power devices that cant parse JavaScript quickly: For example, smart TVs, watches, and other IoT devices, or lower spec smartphones. It also means Svelte shines where bandwidth is limited, which again makes it a perfect fit for older devices and users who might have poor internet connections.

Because Svelte is a compiler, you always get the minimum subset of features required by your app. For example, the Svelte implementation of the TodoMVC weighs 3.6kb zipped. For comparison, React plus ReactDOM without any app code weighs about 45kb zipped. Even if your app is only made of one component, you still have to serve the 45kb that is React itself.

Interoperability

When you want to use a specific npm library, you can only do so if youre already using the framework that the library was designed for. If the library was built with React and youre using Angular, then tough luck.

However, if the library was written with Svelte, apps that use it can be built using whatever JavaScript technology you like. This is because the Svelte app is just JavaScript at the end of the day.

This means that while the ecosystem of dedicated Svelte packages and plugins is comparatively small, you can still easily use any framework-agnostic package. I personally havent struggled to find what Im looking for in terms of external libraries.

Young library ecosystem

While on the subject of external libraries, Svelte options are fewer in number and generally less mature. Depending on your project and team, this could be irrelevant, inconvenient, or a blocker. I have personally struggled with getting a component library that gives me everything I need.

If I was using React, Id be spoilt for choice because there are big players like Material UI or Chakra UI. Sure, theres Svelte MUI but its nothing close to its React counterpart. That said, daisyUI has been really great and provided most of the things I need.

Apart from the UI components, which I have the escape hatch of building myself, this is not a big issue as Ive been building Pro-Search to be as light as I can possibly make it. When you do need to build something yourself, Svelte makes it comparatively simple to do so.

Best practices are still evolving

Svelte conventions and cultural knowledge like patterns, anti-patterns, best practices and consensus libraries are sparse and under-developed. People who adopt it today will have to think through problems that other communities have common solutions for, making the learning curve temporarily steeper.

While React forms are a nuisance, there are some established patterns to ease the pain even without using libraries. We all know of Kent C. Dodds popular approach on How to use React Context effectively, and you see it popping up in many libraries.

These patterns and practices dont exist with Svelte. For example, I couldnt find a best practice to use a Svelte store, so I created my own way. Theres also no recommended way to structure components, so I used what Im used to in React.

This, however, is obviously a temporary problem and will disappear as adoption increases.

Reflections on using Svelte

After using Svelte for more than six months on Pro-Search, I can say its an enjoyable developer experience that doesnt compromise on user experience. I was able to pick it up and get going in building a relatively complex application in no time. Sure, there are things that are still in the works, but the API is very intuitive and the knowledge I already had from React was quite transferable.

When using Svelte, I always feel like Im just writing regular HTML, CSS and JavaScript, and whatever powers are given to it by the framework are done under the hood. I really think this is how writing for the modern frontend web should feel. Im excited for the future of Svelte, and Im excited to be joining the community so early. Hopefully this is the start of many years of blissful coding!

Should you use Svelte right now?

Well, it depends.

Are you learning your first framework? If so, whats your goal? If youre looking for an easy tool to learn, for something that will empower you to build interactive UIs, or just for some additional knowledge and experience, Id recommend Svelte wholeheartedly. Theres no wrong choice when it comes to developing your own skills, and Svelte is easy for beginners to learn quickly.

On the other hand, if youre learning in the hopes of getting a job with your newfound skills, it would be hard to recommend anything other than React because its the largest framework by far in terms of market share and jobs available. The industry went in heavily on React, and I dont see that changing any time soon. There arent many employment opportunities for Svelte right now. Because its new, its not easy to get developers who already know it or are interested in learning it. Though, if you already know React, I think its worth learning Svelte for the perspective if nothing else.

Alternately, are you choosing a technology for a relatively new startup or project like me? Svelte will likely enable you to move quicker and build something thats more performant, but hiring or collaborating may be a challenge given the relatively small pool of Svelte developers. Where React, Vue and Angular all have large communities full of resources for you to take advantage of, Svelte can seem comparatively small. The fear, then, is that when or if you need to reach for additional packages to handle things beyond the main frameworks capabilities, you may be left in the rut.

That said, knowing one JavaScript framework tends to make learning a new one easier and Svelte is, in my opinion, the easiest to start with. Any developer whos already familiar with another frontend framework should be able to pick up Svelte pretty quickly, and vice versa.

The future of Svelte

In the State of JS 2021 survey, Svelte had a 90% satisfaction rating, coming a close second to Solid. It also took the top spot as the most loved framework in the 2021 Stackoverflow Developer Survey. All public survey data is going to have biases, but roughly speaking these are great numbers for a small time framework.

Compared to modern mainstream frameworks like React and Vue and their communities, Svelte is smaller and less mature, but its community is active and established. As a result, Svelte is now commonly mentioned in the same breath as React, Vue, Angular, Preact, and Ember.

Unlike React, which has benefited from nearly a decade of optimisation already and may not have a lot left to squeeze out of it at this point, Svelte is comparably young. If Im betting on which framework will improve more in the future relative to its current position, Im backing Svelte no question. And, the bonus to being an early-adopter is that you become one of the initial groups of community contributors.

Its worth mentioning that since Svelte started becoming popular, other frameworks have learned from it leading to some synergies in the communities.

The arguments against adopting Svelte grow fewer everyday.

The end of 2021 came with some exciting news: Svelte and Vercel announced that Svelte creator Rich Harris will join Vercel to work on Svelte full-time. This should accelerate the development of features, and hopefully push Svelte further into the mainstream.

I hope Ive made you as excited about Svelte as I am! I encourage you to try it out on your own, even if its just playing around in the Svelte tutorial.

If you have any questions or thoughts, reach out!

The Pro-Search repo is public here! so feel free to contribute.

Resources

If youre new to Svelte, these three presentations by Rich Harris, the creator of Svelte, are a popular way to get a pretty comprehensive introduction of what it is, why it exists, and what it wants to achieve.

How to gradually adopt TypeScript

Bhekani Khumalo — Tue, 10 May 2022 00:25:06 +0000

This article is part two of this series on TypeScript. Check out part one here

Typescript is great! I think we can all agree on that now. But when you have a massive complex JavaScript project you probably don't want to nuke it all and replace it with TypeScript. The TypeScript errors will likely overwhelm you and you might end up giving up on what would have been the best decision of your project's life.

Fortunately, you don't have to do that because TypeScript is not an all or nothing deal. I know many people often cite that JavaScript is valid TypeScript but that's not what I mean. I'm referring to the fact that you can gradually adopt TypeScript. You can gradually turn it on in your JavaScript files even before you turn them into TypeScript files. That way you can enjoy the benefits of TypeScript even before you make the commitment.

It's more than likely that you're already enjoying some of the benefits of TypeScript in your JavaScript files right now even without doing anything. This is because most modern code editors and IDEs already have great typescript support and use TypeScript to provide some of their features. I work in VSCode so all the references I will make are to it.

Now, let's learn how to incrementally add TypeScript to your JavaScript files.

Say we have the following code

// src/utils.js

export function add(num1, num2) {
  return num1 + num2;
}

and

// src/index.js
import { add } from './utils.js';

const result = add(2, 5);

console.log(result);

This currently doesn't really give us much type information and is not type-safe. What is the minimum amount of typing that we can add to get safety? We can use JSDoc.

// src/utils

/**
* Multiply two numbers
*
* @param {*} num1 
* @param {*} num2 
* @returns {*}
*
*/
export function add(num1, num2) {
  return num1 + num2;
}

Now if we go to the index.js file and hover over the add method it will have types already, not very safe but typed.

// src/index.js
import { add } from './utils.js';

const result = add(2, 5); // add(num1: any, num2: any): any

console.log(result);

We can specify the types like this:

// src/utils.js

/**
* Multiply two numbers
*
* @param {number} num1 
* @param {number} num2 
* @returns {number}
*
*/
export function add(num1, num2) {
  return num1 + num2;
}

Now if you go to index.js and hover on add you'll get the type information.

// src/index.js
import { add } from './utils.js';

const result = add(2, 5); // add(num1: number, num2: number): number

console.log(result);

const result2 = add('2', 5); // no error

console.log(result2);

Note that at this stage if you provide the wrong types you won't get any errors. This is step 1, which is letting the editor tell us the type of information only.

To go a step further we can add the @ts-check comment to the top of the file and this will now do the static type checking and alert us when there is an error.

// src/index.js
// @ts-check
import { multiply } from './utils.js';

const result = multiply(2, 5); // add(num1: number, num2: number): number

console.log(result);

const result2 = add('2', 5); // Argument of type 'string' is not assignable to parameter of type 'number'.

console.log(result2);

We can see from this that most of the types are already available through these JSDoc comments. This is JSDoc support in TypeScript. You can convert your JavaScript project into a JSDoc powered TypeScript project first before moving to full TypeScript. This will make moving to TypeScript relatively trivial because all the type information will already be available.

This is fine but what if we want to use more complex types. How do we define those with JSDoc? To illustrate this, let's add another function to our utils.js file.

// src/utils.js
...

export function getAddress(input) {
  if (!input?.address?.line1) {
    throw new Error("Invalid address");
  }

  return input.address.line1;
}

and over in index.js:

// src/index.js
// @ts-check
import { add, getAddress } from './utils.js';

const result = add(2, 5);

console.log(result);

const firstAddressLine1 = getAddress({ address: { line1: "123 Main Street" } }); // getAddress(input: any): any

console.log({ firstAddressLine1 });

const firstAddressLine2 = getAddress({ name: "Stephen Strange" }); // no error

console.log({ firstAddressLine2 });

Notice that we have intentionally included code that should give us an error but JavaScript is not yet smart enough on its own to alert us of this. Second, for us to know what the getAddress function expects as valid input we need to look in the source code of getAddress.

To add type information to this we add a JSDoc comment again. And for this we can use JSDoc syntax or TypeScript syntax, both will work but typescript syntax is simpler to write, so we'll use that.

// src/utils.js
...

/**
 * @param {{ address: { line1: string } }} input
 * @returns {string}
 *
 */
export function getAddress(input) {
  if (!input?.address?.line1) {
    throw new Error("Invalid address");
  }

  return input.address.line1;
}

What we've done here is to tell TypeScript that this should only accept an object that has a property address which is an object with a line1 property in it that is a string.

Here's the JSDoc version of the type in case you're curious:

/**
 * @param {object} input
 * @param {object} input.address
 * @param {string} input.address.line1
 * @returns {string}
 *
 */

Now that we've added the type, we'll get an error we we gave an input with the wrong type:

// src/index.js
// @ts-check
import { add, getAddress } from './utils.js';

const result = add(2, 5);

console.log(result);

const firstAddressLine1 = getAddress({ address: { line1: "123 Main Street" } }); // getAddress(input: { address: { line1: string } }): string

console.log({ firstAddressLine1 });

const firstAddressLine2 = getAddress({ name: "Stephen Strange" }); //  
/* Argument of type '{ name: string; }' is not assignable to parameter of type '{ address: { line1: string; }; }'. Argument of type '{ name: string; }' is not assignable to parameter of type '{ address: { line1: string; }; }'. */

console.log({ firstAddressLine2 });

Note that even if the value is supplied from a variable it's still smart enough to know that the structure is wrong:

// src/index.js
// @ts-check
import { add, getAddress } from './utils.js';

const result = add(2, 5);

console.log(result);

const firstAddressLine1 = getAddress({ address: { line1: "123 Main Street" } }); // getAddress(input: { address: { line1: string } }): string

console.log({ firstAddressLine1 });

const input = { name: "Stephen Strange" };
const firstAddressLine2 = getAddress(input); //  
/* Argument of type '{ name: string; }' is not assignable to parameter of type '{ address: { line1: string; }; }'. Argument of type '{ name: string; }' is not assignable to parameter of type '{ address: { line1: string; }; }'. */

console.log({ firstAddressLine2 });

With reference to what we spoke about concerning structural typing in part one of this series, note that if we provide a type with an address property that is an object with a line1 property that is a string, it is happy even if the object has other members:

// src/index.js
// @ts-check
import { add, getAddress } from './utils.js';

const result = add(2, 5);

console.log(result);

const firstAddressLine1 = getAddress({ address: { line1: "123 Main Street" } }); // getAddress(input: { address: { line1: string } }): string

console.log({ firstAddressLine1 });

const input = {
  name: "Stephen Strange",
  address: {
    line1: "123 Main St",
  },
};
const firstAddressLine2 = getAddress(input); // 

console.log({ firstAddressLine2 });

An additional benefit is that when we provide types like this. The code itself is already self-documenting. We no longer have to go into the source of the getAddress function to understand what kind of input it expects or what it will return.

The way we've done it here is the least pedantic that TypeScript can be. If we remove the @ts-check comment we stop getting the errors but we still get the developer tooling that typescript provides.

This is a nice place to consider how we would do named types. To show this, let's add another function to our utils.js file:

// src/utils.js
...

export function storeAddress(name, line1, city, postCode) {
  return {
    name,
    address: {
      line1,
      city,
      postCode,
    },
  };
}

The return type of storeAddress is compatible with the input type of getAddress so it would be helpful if we can define a type that can be passed around between the two. First, let's add the types for the parameters of storeAddress:

// src/utils.js
...

/**
 * @param {string} name
 * @param {string} line1
 * @param {string} city
 * @param {string} postCode
 */
export function storeAddress(name, line1, city, postCode) {
  return {
    name,
    address: {
      line1,
      city,
      postCode,
    },
  };
}

With this, Typescript can already infer the return type of storeAddress, you can see this by hovering on storeAddress.

// src/utils.js
...

/**
 * @param {string} name
 * @param {string} line1
 * @param {string} city
 * @param {string} postCode
 */
export function storeAddress(name, line1, city, postCode) {
  /*
      function storeAddress(name: string, line1: string, city: string, postCode: string): {
        name: string;
        address: {
          line1: string;
          city: string;
          postCode: string;
        };
      }
  */

  return {
    name,
    address: {
      line1,
      city,
      postCode,
    },
  };
}

If we want to create a named type we can do it by creating a JSDoc that's not attached to anything. Then we can specify that new type where we want to use it like this.

// src/utils.js
...

/**
 * @typedef {object} UserInfo an object with address information
 * @property {string} name
 * @property {{ line1: string, city: string, postCode: string }} address
 * 
 */

/**
 * @param {string} name
 * @param {string} line1
 * @param {string} city
 * @param {string} postCode
 * @returns {UserInfo}
 */
export function storeAddress(name, line1, city, postCode) {
    return {
        name, 
        address: {
            line1, 
            city, 
            postCode, 
        }
    }
}

/**
 * @param {UserInfo} input
 * @returns {string}
 *
 */
export function getAddress(input) {
    if (!input?.address?.line1) {
        throw new Error('Invalid address');
    }

    return input.address.line1;
}

The reason we can do this is that comments are just a black hole that can be used to add many things and compilers that don't support those things will just ignore them.

Now our functions are fully typed with a named type that can be passed around. Now we can update the index.js file so that everything works:

// src/index.js
// @ts-check
import { add, getAddress, storeAddress } from './utils.js';

const result = add(2, 5);

console.log(result);

const input = storeAddress("Stephen Strange", "123 Main St", "London", "ABC123"); // storeAddress(name: string, line1: string, city: string, postCode: string): UserInfo

const addressLine1 = getAddress(input); // getAddress(input: UserInfo): string

console.log({ addressLine1 });

Specifying types using JSDoc like thiswhile powerfulis a little tedious and unfriendly. The next question then is how can we specify types in a friendlier way? We can do this using a .d.ts file.

As usual, let's start by adding another function to utils.js:

// src/utils
...
export function createUser(name, age, city) {
  return {
    name,
    age,
    city,
  };
}

We can now create a new types.d.ts file like this:

// src/types.d.ts
export interface User {
  name: string;
  age: number;
  city: string;
}

And back in utils.js we can modify the new createUser function like this:

// src/utils
...

/**
 * @param {string} name
 * @param {number} age
 * @param {string} city
 * @returns {import('./types').User} User
 *
 */
export function createUser(name, age, city) {
  return {
    name,
    age,
    city,
  };
}

Now we can update index.js to this:

// src/index.js
// @ts-check
import { 
    add, 
    getAddress, 
    storeAddress, 
    addAlbum 
} from './utils.js';

const result = add(2, 5);

console.log(result);

const input = storeAddress(
    'Bhekani', 
    '123 Main St', 
    'London', 
    'ABC123',
);
const addressLine1= getAddress(input);

console.log({ addressLine1 });

const newUser = createUser("Benedict Wong", 50, "London"); // createUser(name: string, age: number, city: string): User

console.log({ newUser });

Now if we want to specify the parameters of the function using typescript syntax as well, then we'll need to extract the createUser function into its own file so that we can write its own .d.ts file.

// src/createUser.js

export function createUser(name, age, city) {
  return {
    name,
    age,
    city,
  };
}

Note that we can't just create a utils.d.ts file because we would then need to describe the shape of the entire file. So let's do it for createUser

// src/createUser.d.ts

export function createUser(name: string, age: number, city: string): User;

TypeScript prioritises looking at the .d.ts files ahead of the .js files to figure out the type information. If we wanted to make the definition of createUser available globally we would use declare function ... instead of export function ....

The trade-off here with using .d.ts files is the loss of co-location of our type definitions. But the benefit is that we get to use the typescript syntax which is more succinct than the JSDoc syntax.

We have achieved all this without having to install the TypeScript compiler. This is because the code editor (VSCode in my case) already has TypeScript support built in. But of course, there's the final step from this, which is to write this as a .ts file. This would then need us to add the typescript compiler.

So let's create a new file:

// src/addMovie.ts

interface Movie {
    title: string;
    genre: string;
    year: number;
}

export function addMovie(title: string, genre: string, year: number): Movie {
    return { title, genre, year };
}

This doesn't immediately work. We can use ts-node to run it or we can install the typescript compiler by running npm install --save-dev typescript. Next, run npm init -y then in the package.json file, add the following build script:

// package.json
...
"scripts": {
    "build": "tsc",
    ...
}
...

Now we need a tsconfig.json file. We can auto-generate this with npx tsc --init. After this, if you run npm run build you should get a .js file next to the .ts file. You still have all the information in your .ts file and everything is co-located. But you also have everything working with the .js files.

And that's it, we've incrementally added TypeScript to our little project. Managing to go a big part of the way before we had to install the TypeScript compiler.

A key takeaway is that migration to TypeScript can be gradual, so team members can learn the new syntax on the job, and you can start to get a feel of the real benefits before fully committing. If you have a massive project that's in motion, you don't have to make everyone drop tools and start converting things to typescript. You can even get the type checking on files and projects that you never intend to convert to typescript.

I hope this convinces some of the remaining holdouts out there. Or helps anyone who can't convert their project fully to TypeScript for whatever reason.

Typescript under the hood

Bhekani Khumalo — Thu, 14 Apr 2022 16:12:07 +0000

So you've been using TypeScript for a while now and finally, you're wondering how it does what it does. The relationship between TypeScript and JavaScript is a pretty interesting one and one from which we can learn some interesting things about how programming languages work under the hood.

When most of us learn a technology, we learn the technology without learning the technology inside the technology. We learn how to use it without worrying about how it does what it does.

Recently, I've taken an interest in looking under the hood (essentially doing a code review of the tools I use). I've learned a lot through this. More than just about the specific technology I'll be looking at.

In this article, we'll do a high-level tour of how Typescript works under the hood and hopefully set the stage for more Typescript related articles in the future.

You might know all this. If you do it's great! Correct me where I go wrong and explain better where I'm unclear. If not, then it will be very useful. Hopefully, all of us will find something we didn't know.

Let's go!

Definition

TypeScript is an open-source language that builds on JavaScript by adding static type definitions and static type checking. These types provide a way to describe the shape of an object, providing better documentation, and allowing TypeScript to validate that your code works correctly. Writing types can be optional in TypeScript because it has powerful type inference which allows you to get a lot of power without writing additional code.

Being strongly typed on top of a weakly typed platform enables TypeScript to do some language syntax and implementation that would be difficult, if not impossible, to do in traditional strongly typed languages.

Why?

The reason for TypeScript's existence can be summarised with these three ideas.

Fail Fast, Fail Often : a philosophy that values extensive testing and incremental development to determine whether an idea has value. An important goal of the philosophy is to cut losses when testing reveals something isnt working and quickly try something else, a concept known as pivoting. Achieving this means putting in systems that can speed up processes and allow for quick feedback.
Fail first : put the steps that cover the most likely or impactful failures first. If there is a part of the process that is likely to break frequently without someone noticing, test for that early in the process.
Confidence : The biggest and most important reason we test things is confidence. We want to be confident that the code we are writing for the future won't break the app that we have running in production today.

TypeScript allows for your code to fail as you're writing it. That way you have immediate feedback about what will not work and you don't have to discover it down the line. This gives you confidence when you ship that you're shipping the correct thing. We want to see things fail at this stage because of the following factors:

Cost : As you progress in the development process, testing things becomes more costly. This comes as actual money to run tests in a continuous integration environment, but also in the time it takes engineers to write and maintain each individual test.
Scope : The further in the process you go, the more potential points of failure there are and therefore, the more likely it is that a test will break, leading to more time needed to analyse and fix the failures.
Speed: As you move along in the process, the tests typically run slower. This is because the further along you are, the more code you have to test.

How TypeScript works under the hood

When you run a program, what youre really doing is telling the runtime to evaluate the byte-code generated by the compiler from the AST parsed from your source code. The details vary, but for most languages, this is an accurate high-level view. Where TypeScript is special is that instead of compiling straight to byte code, it compiles to JavaScript code! You then run that JavaScript code like you normally wouldin your browser, or with NodeJS, etc.

So when does it make code type-safe? After the TypeScript compiler generates an AST for your programbut before it emits the codeit type checks your code.

In this process, steps 12 use your programs types; step 3 does not. TypeScripts type system is fully erased.

Thats worth reiterating: when the typescript compiler compiles your code from TypeScript to JavaScript, it wont look at your types. That means your programs types will never affect your programs generated output and are only used for type checking. This feature makes it foolproof to experiment with, update, and improve your programs types, without risking breaking your application.

This also means that all valid JavaScript code is valid TypeScript code. This is important because it means you can run the TypeScript compiler over JavaScript and get TypeScript's fantastic auto-complete without using any types at all. In fact, the TypeScript team handles a lot of the editor integration for TypeScript, which allows us to get a consistent experience across many editors. Note that TypeScript's editor integration supports JavaScript, so it's likely that if you're using JavaScript, you're already using TypeScript under the hood.

Structural Type System

One of TypeScripts core principles is that type checking focuses on the shape that values have. This is sometimes called duck typing or structural typing. Before we explore the characteristics of structural typing, let's talk a bit about C# and Java for comparison.

In C# any Javawhich use reified, nominal type systemsany value or object has one exact type - either null, a primitive, or a known class type. The definition of this type will reside in a class somewhere with some name, and we cant use two classes with similar shapes in place of each other unless theres an explicit inheritance relationship or commonly implemented interface. The types we wrote in the code are present at runtime, and the types are related via their declarations, not their structures.

In TypeScriptwhich uses structural typingits better to think of a type as a set of values that share something in common. Because types are just sets, a particular value can belong to many sets at the same time. TypeScript provides several mechanisms to work with types in a set-like way, for example, unions and intersections, and youll find them more intuitive if you think of types as sets.

In TypeScript, objects are not of a single exact type. For example, if we construct an object that satisfies an interface, we can use that object where that interface is expected, even though there was no declarative relationship between the two.

interface Pointlike {
  x: number;
  y: number;
}
interface Named {
  name: string;
}

function logPoint(point: Pointlike) {
  console.log("x = " + point.x + ", y = " + point.y);
}

function logName(x: Named) {
  console.log("Hello, " + x.name);
}

const obj = {
  x: 0,
  y: 0,
  name: "Origin",
};

logPoint(obj); // 
logName(obj); //

The obj variable is never declared to be a Pointlike or Named type. However, TypeScript compares the shape in the type-check. They have the same shape, so the code passes. TypeScripts type system is also not reified, that is theres nothing at runtime that will tell us that obj is Pointlike. In fact, the Pointlike type is not present in any form at runtime.

There is also no difference between how classes and objects conform to shapes:

class VirtualPoint {
  x: number;
  y: number;

  constructor(x: number, y: number) {
    this.x = x;
    this.y = y;
  }
}

const newVPoint = new VirtualPoint(13, 56);
logPoint(newVPoint); // logs "13, 56"

If the object or class has all the required properties, TypeScript will say they match, regardless of the implementation details.

OOP programmers are often surprised by two particular aspects of structural typing. The first is that the empty type seems to defy expectation:

class Empty {}

function fn(arg: Empty) {
  // do something
}

fn({ k: 10 }); // No error, but this isn't an 'Empty'

TypeScript determines if the call to fn here is valid by seeing if the provided argument is a valid Empty. We can see that { k: 10 } has all the properties that Empty does because Empty has no properties. Therefore, this is a valid call!

The second frequent source of surprise comes with identical types:

class Car {
  drive() {
    // hit the gas
  }
}
class Golfer {
  drive() {
    // hit the ball far
  }
}

let w: Car = new Golfer(); // No error?

Again, this isnt an error because the structures of these classes are the same.

Will it last?

Should you invest the time to understand TypeScript deeply? Won't it lose favour like flow, CoffeeScript, etc?

The underlying tension to all this is the divergence between TypeScript and JavaScript. Typescript pitches itself today as JavaScript with types, i.e., if JavaScript evolves, then TypeScript evolves in the same way. And that's the biggest argument for why it's likely going to stay for long.

The TypeScript team contributes to the TC39 committees, which help guide the evolution of the JavaScript language. For example, the TypeScript team championed proposals like Optional Chaining, Nullish coalescing Operator and Throw Expressions. And more recently have submitted a proposal to officially add types to JavaScript.

Adopting TypeScript is not a binary choice. There's a sliding scale of TypeScript support that you can get in any project. You can start by annotating existing JavaScript with JSDoc, then switch a few files to be checked by TypeScript and over time prepare your codebase to convert completely.

Finally, TypeScripts type inference means that you dont have to annotate your code until you want more safety.

Not convinced? Check out TJ VanTollon's take on this talk:

Speaking of gradually adopting TypeScript. Want to know how you can do that? Keep an eye out for my next blog post for a walkthrough.

Onboarding Pains: Get new hires up and running faster and more efficiently

Bhekani Khumalo — Tue, 16 Feb 2021 23:00:30 +0000

Wikipedia defines onboarding as the mechanism through which new employees acquire the necessary knowledge, skills, and behaviours to become effective organizational members and insiders.

I started a new job recently with what I believe is an awesome company. I am a new hire at a company again, so I am going through the onboarding process again — one of the best onboarding processes I have ever gone through I must say. This got me reflecting on the onboarding experiences I have had.

The goal of the process is to get new hires up and running as fully functional and autonomous members of the team and the company as fast as possible. Therefore, it is important to ensure that all the onboarding materials provided to them is as easy to parse as possible and makes this process as efficient as it can be. Unfortunately, this does not always happen, this article is a short compilation of some onboarding frustrations I have experienced in my Software Engineering journey. I hope it will help you improve your processes. I also hope that only a few people can relate to my experiences.

This is in no way exhaustive and I may come back in the future to add more things if I learn or remember something else, or I will write a follow-up blog with the new things (the second idea is probably the better one). With that out of the way, let's go.

All the acronyms and abbreviations

Reading a document with many abbreviations and acronyms that are not explained can be a big pain and can make one feel like an outsider. You must search through alternative company documentation or contact a team member on every turn which adds some serious drag to the process. So do not assume context, linguistic or cultural-based familiarity. When you mention terms that do not have a commonly known meaning outside your company, explain them, do not assume that everyone knows them, particularly in onboarding document. Extra points for explaining their meaning as close to where they're used as possible. Needing to refer to a separate document just to get the meanings of words and acronyms can add also add some unnecessary friction. If defining in line is not possible for some reason, then a supplement or definition of terms section at the beginning or end should make easy reference.

... do not assume context, linguistic or cultural-based familiarity.

Therefore, explain as much as you can. After all, we software people speak a lot about readability when referring to writing code —- writing meaningful variable names, avoiding abbreviations that aren't commonly known, explaining complex logic in source comments, giving the context of changes in commit messages, etc. —- so the understanding of efficiency gains when things are easy to read are well known to us. Let's not forget that in onboarding documentation. Do this when talking to new people as well. This is even more important with global teams where people have different native languages and cultural contexts.

Paying that extra bit of attention will help create a culture where newcomers and people outside your immediate team can feel like, 'yes, that's for me too'.

So many assumptions

As you craft your onboarding documentation, realise that your new hire probably does not know much about the product or project they will be working on. They have no historical context for why things are the way they are. They are not familiar with the team’s choices for various processes such as code reviews, version control management, release management, and countless other things. And they don’t know about random idiosyncrasies that have been adopted by the team over time, things that are probably not documented but people just "seem to know". Without that little additional context that everyone seems to have, a lot of technical content can feel just a little out of reach even for very competent people and exclude them from being able to participate as fast as they could.

I know, I know we are engineers, and we are hired because we are supposed to know what we are doing but it does not take long usually to be clear on as much as possible and not to assume that someone knows something. Even when dealing with an experienced engineer, offer to walk them through how the version control process works at this company. Let them be the ones to turn down the offer if they do not need it. That added bit of helpfulness pays off with dividends down the line.

Without that little additional context that everyone seems to have, a lot of technical content can feel just a little out of reach even for very competent people

Consider that the meanings of things can change over time and the terminology used for a given subject can also change over time. So even if the 'Voldermort Pipeline' means something to everyone today, the context that gives it meaning might be lost in a few years. If that happens, all the witty documentation you wrote without explaining things could become difficult to parse for everyone. So, avoiding assumptions in your documentation is useful for more than just easing the process for new hires.

No more tests, please

If the hiring process was done right, you should have already decided whether this is a suitable candidate for the job or not. If other things need to be figured out, you have the entire probationary period to reassess your decision. Therefore, onboarding time is not the time for random quizzes and knowledge tests. Your new hire is already burdened with the task of learning this new company, this new team, this innovative technology, this novel approach, etc., the last thing they need is to attend to a random spot check of their knowledge.

"There's no need to say, 'apply pressure to the right side of the mouse', when 'right-click' would do." - Aer Parris

Research shows that accessible design is good for everyone — even people without disabilities or impairments. For example, auto-complete initially made for people with low dexterity, is now widely used by all and contrast and colour guidelines, created to help people with vision impairments, help us all see better. The same is true for writing documentation. Sure, your teammates are smart people with above-average reading levels, and you want your new hires to have the same intellectual acuity, but they are also busy. So, do everyone a favour and save them time by not making them have to parse complicated language and sentence structure. In the words of Aer Parris, "There's no need to say, 'apply pressure to the right side of the mouse', when 'right-click' would do."

Summing it up

Writing good onboarding guides may take more time up-front, but it pays off down the road when new members of the team can easily and efficiently get up and going and contributing to the work. After all, your new hire is already buckling under the weight of tonnes of things they need to get familiar with in this new place, help them win back some precious mental headspace to get work done.

Forming highly efficient and highly functional teams is ultimately about building a community, and communities need to be sensitive to the needs of potential new community members. However, community is the most complex part of building a team because it is the most abstract. You cannot solve it with algorithms and formulas, you need to pay attention to things like empathy and inclusion.

Forming highly efficient and highly functional teams is ultimately about building a community, and communities need to be sensitive to the needs of potential new community members.

Finally, your latest hire has the best knowledge about how good your onboarding material is. If making the time to fix up your documentation is difficult, allow them to update the parts that they found hard to follow while their experience with it is still fresh. That way, your documentation will get better with every new hire and stay up to date since it is highly likely that some things have changed since the guide was written.

Is any of this stuff relatable? Do you have any of your thoughts and experiences to share? I'd love to hear them in the comments below.

Explaining code quality to management: The technical debt metaphor

Bhekani Khumalo — Mon, 16 Sep 2019 13:03:39 +0000

Managing internal code quality is an increasingly critical aspect of producing cost-effective, timely, and high-quality software. But it can often be difficult to explain what this internal code quality is to non-technical people, unfortunately, management usually consists of non-technical people as far as coding is concerned. The technical debt metaphor is one way that can be used to clarify this. In this article, I will define external and internal quality and then talk about technical debt, it's definitions and how it is used as a metaphor for discussing quality with non-technical business people.

That said, if you just came here for a definition, here it is:

A term used to describe the obligation that a software organization incurs when it chooses a design or construction approach that is expedient in the short term but that increases complexity and is more costly in the long term. It is a metaphor that facilitates the communication between business and technical people regarding implementation artefact inadequacies and the risks they carry.

TL;DR

Software systems are prone to the build-up of deficiencies in internal quality that make it harder than it would ideally be to modify and extend the software. In their haste to deliver features (usually do due to time pressure from management), developers sometimes engage in less-than-optimal coding practices. If not addressed, these shortcuts can ultimately yield rework costs that offset the benefits of rapid delivery.

Technical Debt is a metaphor, coined by Ward Cunningham, that frames how to think about dealing with this by viewing it in the same way as financial debt. The extra effort that it takes to add new features to code that was not done right is the interest paid on the debt. The longer you take to fix the code, the more time it takes to extend or maintain it and the higher the interest you pay on the technical debt. Taking shortcuts to expedite the delivery of features in the short term incurs technical debt, analogous to financial debt, that must be paid off later to optimize long-term success.

Let's break it down

What should be understood first is that technical debt is connected to the quality of software, so before going too far, let's first talk a little bit about quality.

There are two types of quality; external quality and internal quality. External quality is the quality that can be perceived by a user or a customer - that might be things like performance, security, scalability, stability, responsiveness, etc. Anything that can be measured or experienced by users. Because it is a feature of the product, it is usually managed by the product owner or business people, they can easily draw the link between this quality and how the users will respond to the software.

The more complex part of software development is that there is also internal quality. Internal quality can only be perceived by developers or technical people who can understand the code. It's anything that makes maintaining or extending the code easier or harder. Examples might be existence or lack of tests - if there are more tests then the code is easier to change, it might be about the architectural styles used, it can also be about coding issues - whether the code is too complex. Software developers talk a lot about quality code and good code but the value of this is not always immediately obvious to non-technical people if's not always clear to them why we should invest in code quality when the software already works. That's where the technical debt metaphor comes in.

Technical debt is used to describe code that is not quite right, to put it loosely. We use this metaphor of debt to draw comparisons with financial debt which more people are able to comprehend easily. This helps in explaining that if we want to build something on top of code that is not quite right, over time it will get expensive to extend that kind of code and it will take longer to build new features if the code base is of bad quality.

The term was coined by Ward Cunningham, one of the authors of the Agile Manifesto. He said that some problems with code are like financial debt. It’s ok to borrow against the future, as long as you pay it off. In 1992, at the OOPSLA conference, he famously said the following (slightly paraphrased):

Shipping first-time code is like going into debt. A little debt speeds development so long as it is paid back promptly with refactoring. The danger occurs when the debt is not repaid. Every minute spent on code that is not quite right for the programming task of the moment counts as interest on that debt. Entire engineering organizations can be brought to a stand-still under the debt load of an un-factored implementation, object-oriented or otherwise.

This basically says that technical debt is about shipping something quickly and thereby going into debt where you will need to repay that debt by increasing the quality later on. If you don't do that, then you will need to pay increasingly higher interest rates as your productivity goes down and you're slowed down in your development. The interest is the extra time you will spend refactoring the code later as opposed to doing it now. Ward explains this much clearer here:

With borrowed money you can do something sooner than you might otherwise, but until you pay back that money you will pay interest. I thought borrowing money was a good idea. I thought that rushing software out the door to get some experience with it was a good idea. But that, of course, you would eventually go back and as you learned things about that software you would repay that loan by refactoring the program to reflect your experience as you acquired it.

This is a good metaphor for talking to management because they should be familiar with financial terms and it is easier to talk to them in these terms and tell them that this is just like getting a loan at the bank, you get some benefit for some time but at some point you will need to repay it and you repay it with interest, the longer you take to repay the higher the interest.

Ward, however, makes it clear that technical debt is not to say you should write code poorly with the expectation that you will make it good later, writing poor code is never a good thing. The idea is that you can write code that reflects your current understanding of the problem at the time even if that understanding is partial. So that when the time comes to refactor it's clear what you were thinking and you can then align it with your new understanding and that time spent going back to realign the code is the interest on the debt.

A different definition that, perhaps, many are familiar with is by Steve McConnell. He says technical debt is:

A design or construction approach that is expedient in the short term but that creates a technical context in which the same work will cost more to do later than it would cost to do now (including increased cost over time).

Put simply, it means doing something quick and dirty and we gain something in the short term but with the knowledge that it will bite us in the long term. A delicate balance is needed between the desire to release new software features rapidly to satisfy users and the desire to practice sound software engineering that reduces rework and improves the efficiency of maintenance and extension. This is especially true because internal quality sooner or later becomes external quality and that's something that's important to communicate. For instance, if we have a bad code base, we get more and more bugs, we slow down and that will eventually bubble up to all kinds of stakeholders of a project.

Ultimately technical debt is not a developer problem, it's a company problem. If you accrue too much technical debt, in the worst cases, whole engineering departments can come to a standstill. It can be argued that managing technical debt is one of the key points in successfully developing commercial software. Hopefully, this short piece has clarified your understanding of technical debt and will help you out the next time you try to explain why you need to fix code that works instead of working on new features.

In the next article, I will talk about whether technical debt is entirely bad and how to handle it. Keep an eye out for that one.

Supercharge your Git History with better commit messages

Bhekani Khumalo — Tue, 03 Sep 2019 16:02:32 +0000

Here are some lessons I've picked up about writing Git commit messages that I think every developer should learn and implement. Done right, it will increase the usefulness of your Git history and save your team a ton of time when maintaining code.

TL;DR

Summarize changes in around 50 characters or less

More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. The first line is treated as the subject of the 
commit and the rest of the text as the body. The blank line 
separating the summary from the body is critical (unless you omit 
the body entirely); various tools like `log`, `shortlog` and 
`rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.

Further paragraphs come after blank lines.

 - Bullet points are okay, too
 - Typically a hyphen or asterisk is used for the bullet, preceded
   by a single space

If you use an issue tracker, put references to them at the bottom,
like this:

Resolves: #123
See also: #456, #789

Why good commit messages matter

A project’s long-term success depends (among other things) on its maintainability, and maintainers have few tools more powerful than the project’s log. When done right, the Git history can be a living, accurate and searchable record of how and why a project's code is the way it is. It will make reviewing the commits and pull requests of others easier to do without the need to consult them because it makes understanding why something happened months or years ago not only possible but efficient.

The ability to document code progression effectively is just as important as writing clean code or readable tests. Although code itself should be self-documenting, on its own it doesn’t tell the story of why the code is the way it is or how it came to be. A well-crafted Git commit message can communicate context about a change to fellow developers (and to your future self). A diff will tell you what changed but, when done well, the commit message can properly tell you why. Peter Hutterer put this point really well:

Re-establishing the context of a piece of code is wasteful. We can’t avoid it completely, so our efforts should go to reducing it [as much] as possible. Commit messages can do exactly that and as a result, a commit message shows whether a developer is a good collaborator.

There is a vicious cycle here: if the commit history is unstructured and inconsistent, no one spends much time using or taking care of it. And because it doesn’t get used or taken care of, it becomes more unstructured and inconsistent.

It’s worth taking the time to learn how to care for your Git history properly. It may be a hassle at first but it will become habit quickly, and eventually a source of pride and productivity for all involved.

Atomic Commits

Before getting into how to write a good commit message let's take a short look at the importance of making atomic commits.

Large commits can be difficult to read, especially when they contain changes which are unrelated. It can be difficult to think about how you might split up a large commit, but a useful approach is to think about the purpose of each commit in the same way you might think about writing a checklist for completing the task. Each one should do one specific thing, if you find yourself wanting to use 'and' in your commit message, you're probably committing too much, split it.

Think of atomic commits as the smallest amount of code changed which delivers value – whether it’s tidying up existing code or introducing a new (small) feature. Let's look at an example:

$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: Sansa Stark <sansa@winterfell.com>
Date:   Fri Jan 01 00:00:00 1982 -0200

    Take the Iron Throne at King's Landing

61 files changed, 937 insertions(+), 81 deletions(-)

In this example there are a lot of changes in this one commit. On the surface it might look like all these changes are related. However, if you were to break down the changes, you would have a better sense of what’s going on, for example:

5feaccf Defeat Daenerys
c829cbc Usurp Cersei
a6455f8 Get hitched
b529f6d Leverage on the Stark name
b5bb6e4 Pander to Littlefinger for strategic reasons

Not only is each commit smaller, it also gives you a better story of what has happened to produce the final result. If a user wants to cherry pick specific updates or features they can do that much easier if the commits are atomic.

A formal definition for an atomic commit is, "A single irreducible useful set of changes". The useful in that definition is very important.

Now, on to the main part of the article.

Writing a great Git commit message

I'm sure we can all agree that the Git history often becomes useless when there is no convention and everybody does their own. To create a useful revision history, teams should first spell out their conventions on style, content and metadata of commit message. It's important to remove the guesswork on what commit messages should look like and make it all as simple as possible. The end result will be a remarkably consistent log that’s not only a pleasure to read but that actually does get read on a regular basis.

Fortunately, there are well-established conventions for what makes a good and useful Git commit message. There’s nothing you need to re-invent. Just follow the guideline below and you’ll be on your way to committing like a pro.

1. Limit the subject line to 50 characters

50 characters is not a hard limit but a rule of thumb. Keeping subject lines at this length ensures that they are readable, and forces the author to think for a moment about the most concise way to explain what’s going on.

Tip: If you’re having a hard time summarizing, you might be committing too many changes at once. Strive for atomic commits (as explained above).

Most git tools are fully aware of this convention. They will warn you if you go past the 50 character limit and will truncate any subject line longer than 72 characters with an ellipsis. So shoot for 50 characters, but consider 72 the hard limit.

2. Capitalize the subject line

This is as simple as it sounds. Begin all subject lines with a capital letter. For example:

Make a cup of coffee

Instead of

make a cup of coffee

3. Do not end the subject line with a period

Trailing punctuation is unnecessary in subject lines. Besides, space is precious when you’re trying to keep them to 50 chars or less. Example:

Make a cup of coffee

Instead of

Make a cup of coffee.

4. Use the imperative mood in the subject line

Imperative mood just means “spoken or written as if giving a command or instruction”. A few examples:

Make a cup of coffee
Turn on the computer
Watch YouTube videos

The imperative can sound a little rude; that’s why we don’t often use it. But it’s perfect for Git commit subject lines. One reason for this is that Git itself uses the imperative whenever it creates a commit on your behalf.

For example, the default message created when using git merge reads:

Merge branch 'newfeature'

And when using git revert:

Revert "Add the thing with the stuff"

This reverts commit cc87791524aedd593cff5a74532befe7ab69ce9d.

So when you write your commit messages in the imperative, you’re following Git’s own built-in conventions.

Writing this way can be a little awkward at first. We’re more used to speaking in the indicative mood, which is all about reporting facts. That’s why commit messages often end up reading like this:

Fixed bug
Changing behavior of button

And sometimes commit messages get written as a description of their contents:

More fixes for broken stuff
Sweet new API methods

To remove any confusion, here’s a simple rule to get it right every time. A properly formed Git commit subject line should always be able to complete the following sentence:

If applied, this commit will "Your subject line here"

For example:

If applied, this commit will "Refactor subsystem X for readability"
If applied, this commit will "Update getting started documentation"

Notice how this doesn’t work for the other non-imperative forms:

If applied, this commit will "Fixed bug"
If applied, this commit will "Changing behavior of Button"

Remember: Use of the imperative is important only in the subject line. You can relax this restriction when you’re writing the body.

5. Separate subject from body with a blank line

From the git commit manpage:

Though not required, it’s a good idea to begin the commit message with a single short (less than 50 character) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used throughout Git. For example, Git-format-patch(1) turns a commit into email, and it uses the title on the Subject line and the rest of the commit in the body.

Firstly, not every commit requires both a subject and a body. Sometimes a single line is fine, especially when the change is so simple that no further context is necessary. For example:

Fix typo in introduction to user guide

Nothing more need be said; if the reader wonders what the typo was, they can simply take a look at the change itself, i.e. use git show or git diff or git log -p.

If you’re committing something like this at the command line, it’s easy to use the -m option to git commit:

$ git commit -m "Fix typo in introduction to user guide"

However, when a commit merits a bit of explanation and context, you need to write a body. For example:

Forget that the final GOT season ever existed

The battle of winterfell turned out to be a major dissappointment 
and did not live up to the hype. This commit deletes all evidence 
that the final season ever happened, we prefer to just wonder how
things were going to end that accept how they actually ended.

Commit messages with bodies are not so easy to write with the -m option. You’re better off writing the message in a proper text editor.

The separation of subject from body pays off when browsing the log. Here’s the full log entry:

$ git log
commit 42e769bdf4894310333942ffc5a15151222a87be
Author: kit harington <kit.harington@got.com>
Date:   Fri May 10 00:00:00 2019 -0200

    Forget that the final GOT season ever existed

    The battle of winterfell turned out to be a major dissappointment 
    and did not live up to the hype. This commit deletes all evidence 
    that the final season ever happened, we prefer to just wonder how
    things were going to end that accept how they actually ended.

And now git log --oneline, which prints out just the subject line:

$ git log --oneline
42e769 Forget that the final GOT season ever existed

There are a number of other contexts in Git where the distinction between subject line and body will be useful but none of them will work properly without the blank line in between.

6. Wrap the body at 72 characters

Git doesn't wrap text automatically. When you write the body of a commit message, you must mind its right margin, and wrap text manually.

The recommendation is to do this at 72 characters, so that Git has plenty of room to indent text while still keeping everything under 80 characters overall.

Some Git tools and text editors will already do this for you.

7. Use the body to explain what and why vs. how

This commit from Bitcoin Core is a great example of explaining what changed and why:

commit eb0b56b19017ab5c16c745e6da39c53126924ed6
Author: Pieter Wuille <pieter.wuille@gmail.com>
Date:   Fri Aug 1 22:57:55 2014 +0200

   Simplify serialize.h's exception handling

   Remove the 'state' and 'exceptmask' from serialize.h's stream
   implementations, as well as related methods.

   As exceptmask always included 'failbit', and setstate was always
   called with bits = failbit, all it did was immediately raise an
   exception. Get rid of those variables, and replace the setstate
   with direct exception throwing (which also removes some dead
   code).

   As a result, good() is never reached after a failure (there are
   only 2 calls, one of which is in tests), and can just be replaced
   by !eof().

   fail(), clear(n) and exceptions() are just never called. Delete
   them.

Think how much time the author is saving fellow and future committers by taking the time to provide this context here and now. If he didn’t, that context would probably be lost forever if he leaves.

Focus on making clear the reasons why you made the change, the way things worked before the change (and what was wrong with that), the way they work now, and why you decided to solve it the way you did. In most cases, you can leave out details about how a change has been made. Code is generally self-explanatory in this regard (and if it is so complex that it needs to be explained, then use source comments).

Try to look at the commit from the perspective of the developer maintaining your code. What questions might they ask when looking at your code changes? What might not be immediately obvious?

The future maintainer that thanks you may be yourself!

Closing tips

Revise history before sharing

When writing your code, you are bound to change direction or even make mistakes like introducing typos or bugs.

324d079 Fix typo in enrolment flash message
3a85f77 Only display enrol button for users who can enrol
4cc4778 Allow users to enrol on courses

In this example, the developer has introduced a typo in their first commit, which they have fixed in a later commit.

Before you share your commit history, it’s important to think about what is useful information for someone else reading the history. You shouldn’t think of your Git history as a “truthful” log of what you worked on step-by-step. Just as we refactor code, we should refactor our commits before sharing them with others so that we don't clutter the history.

Git has powerful tools that make it simple to re-order, reword and refactor your commits until they tell the clearest story possible. Use Git's interactive rebasing functionality to tell a clearer story:

$ git rebase -i

3a85f77 Only display enrol button for users who can enrol

773e345 Allow users to enrol on courses

Read Pro Git

Check out the Pro Git book, it's available online for free.

Acknowledgements

This article strongly derives from Chris Beams' article, Seb Jacobs' article, Sebastian Feldmann's talk and my own experience maintaining projects with less that helpful Git histories.

What Civil Engineering Taught Me About Being a Good Software Developer

Bhekani Khumalo — Wed, 31 Jul 2019 21:44:44 +0000

This article was originally published on the Offerzen Blog.

Nine months ago, I was working as a civil engineer and had a scholarship to complete a Ph.D. in chemical and environmental engineering. Today, I’m a geographic information systems (GIS) software developer. Interestingly, I have found that I can apply a lot of what I learned as an engineer to my new role. Here are my four key takeaways from my time as an engineer that have given me an edge in the software development world.

Context

For as long as I can remember, I have loved computers and coding. I taught myself to code in VB6 when I was 14 and I’ve loved it ever since. For one reason or another, though, I didn’t choose that route when I got to university and ended up studying to become a civil engineer.

When I graduated, I started working as an engineer but my passion for computers was still there. Choosing to work with GIS as a civil engineer allowed me to have a very high interaction with computers and, in my free time, I was putting in the effort to further build my knowledge as a software developer. I used a lot of online resources and even took on a few freelance projects to practice my skills and gain experience. It became clearer and clearer that working with computers was what I really wanted to do.

In the last few months, I decided to leave my job as an engineer to turn my passion into a career. While I am really enjoying development, there are a lot of aspects of engineering that I still care about, and from which I have learned a lot of valuable lessons.

Making the shift, I realized that those lessons opened my eyes to a lot of what I was experiencing as a new developer. I’ve found that being aware of certain things has given me a unique perspective and really helped me grow in my new role. Here is what they are.

You should always be open to learning

A good engineer never stops learning

A lot of engineering is based on a foundational science, with certain standards in place that help engineers streamline the application of that science. Despite this, it is still a pretty creative field in that one constantly encounters new problems that push you to think about the established science and standards in new ways.

Engineers need to think about how to challenge what is existing in order to achieve greater efficiency.

This creates the need for continuous learning to keep abreast with changes in the practice.

For example, I was once involved in a water demand management study where we had to develop a strategy for reducing water demand and improving conservation. One of our key discoveries was that the demand management strategy that was in use at the time was based on a study that was done more than two decades before. Because it was working - albeit inefficiently - no one had bothered to update it since it was put in place. So much research had been done in the field that there were many opportunities to reduce the demand quite significantly from water loss in the system. This meant that because those responsible had not continuously learned and applied the advances in the field, each year the utility was losing huge amounts of revenue.

It, therefore, became clear to me that without a firm understanding of the advances, it is difficult to confidently develop solutions to challenges that emerge on a regular basis.

A good developer keeps learning and learns faster

I quickly saw that development is pretty similar in that there is also an underlying science, as well as standards applied to the technologies and frameworks. However, software development changes much faster, which means that older ideas and methods also become obsolete faster. As a developer, you have to keep learning in order to stay relevant. If you slack, your prized skill can become outdated pretty fast.

Software developers are always aiming at a moving target and that is part of what makes it exciting.

As a developer, I experience this quite regularly. The bulk of my work currently involves writing scripts for GIS processing using Python. I have developed some custom modules that a lot of my toolsets refer to for various tasks. Each time there’s a new problem that I need to write a tool for, I do some research for it. While researching for that tool, I usually learn so much that I need to go back to the tools I’ve worked on before to apply my new-found knowledge to them so that they can work better. As a result, my tools are continuously improving because I am continuously learning.

How this has influenced me as a software developer

I have learned from my experience that you should never be satisfied with what you know.

I always seek to learn more and to expand my capabilities, even if I am tackling the same old problem all the time.
I make the effort to read further. I have found that learning something new can widen my perspective and give me a better vantage point, which reveals aspects that I previously could not see.

Learning is a gradual process - you need to take steps to get there

A good engineer should demonstrate that they know how to do the job before they start.

Engineers generally need to figure out, to a high level of detail, how each project will be completed before beginning the task. Yes, there is room for some learning along the way but all of that occurs within a narrow deviation from the plan.

This is important because in most cases there is a lot at stake, including people’s lives and considerably high amounts of public funds. Mistakes are significantly difficult and costly to correct. Therefore, stakeholders want to know whether or not the engineers they are working with can design and construct a sewage treatment plant that will live for 50 years before they allow them to use their money. While engineers have a bit of wiggle room, clients want to know, again to a high level of detail, exactly how they intend to build that plant. They need to know that the engineers have all the requisite knowledge before they allow them to take up the task.

A good developer, by contrast, should get comfortable with learning on the job

Software development works a little differently: It allows for much wider wiggle room. Unlike engineering, where clients want to be sure your practical skillset is solid before signing a contract, in development, they usually want to know whether you have what it takes to figure out what it takes.

Because I was used to having to prove the plan from the get-go as an engineer, this mindset shift was difficult. However, it became clear over time that as a developer, I didn’t need to prove a plan, I needed to prove myself. The plan, after all, would probably mutate along the way.

The first time I wrote a geoprocessing Python script, I had accepted the project without any knowledge of geoprocessing libraries. I had used Python before, though never for any GIS work. I took it up because I understood that the knowledge I had was a good enough starting point, and I had enough time to learn the skills I needed. After burning through some documentation and tutorials, I found a way to start and acquired the rest of the knowledge as it became necessary.

What counts is trusting in your general ability. If you can get started, then you can take the next steps to strengthen your understanding of unfamiliar topics as you go.

How this influenced me as a software developer

While research is important, I’ve learned that you shouldn’t get stuck on it.

I have started letting the requirements of a project direct my learning. I break down the project work into what I do know and start with that.
I research the parts that I don’t know as I get to them so that I can keep moving. I try to remember that some world-changing solutions have been born from such task-driven learning approaches.
I remind myself that I don’t always need to know how to do every single thing that needs to be done. To this day, the tasks that I encounter on the go are what directs my learning. If I had backed out because I didn’t understand all the corners of what was needed, I would probably still be trying to gain the knowledge that would make me feel confident enough to start.

It takes time and commitment to get it right

A good engineer meets the full requirements on the first attempt

When tasked with building a bridge, an engineer needs to design and construct a bridge that is complete and works the way it should the first time. During planning, engineers go through the possibilities, consider the options and come to a final solution.

When engineers design and build, they are working on the final product.
That’s why engineering projects often adopt the waterfall approach to project management: Each step of the process is done to completion before moving on to the next step.

Where redoing something does become necessary, it usually comes at a very high cost. This means that often engineers want to build the final solution the first time around and not have to come back to it for a few decades. Best case scenario, they only have to come back to it for demolition, which has already been factored in during the initial implementation process.

A good developer, however, embraces the fact that they will learn as they go

Development works differently: In a lot of cases, neither the developer nor the client has a very clear picture of what the final product will look like. In most cases, all that is needed is a partially working prototype to understand what to add and what to remove.

Therefore, development often takes a cyclical approach to project management where, during each cycle, we produce a working solution to the best of our abilities, knowledge, and resources at that time. Using that solution, we learn, adapt and use that knowledge for the next cycle to improve the product. This means that it is entirely acceptable to have a product that is never fully done.

In other words, it is never complete but it is always complete for that cycle.

Usually, when the GIS technicians present a problem to me, no one really understands what the solution should look like: All we try to focus on is having a very good understanding of the problem. I used to spend hours trying to figure out the solution until, because of time, I would be forced to just start.

Over time, I have realized that after reaching a first version of the solution, I have gained so much insight into how the final version should function that I can work much faster. I’ve found that my eyes are opened to potential possibilities and pitfalls as I go, which has proved to be more useful than spending time trying to figure them out before building anything.

How this influenced me as a software developer

Most importantly, I have realized that as a developer, you shouldn’t get stuck on the details.

I have started focusing on having a partially working whole to help prioritize the details that need the most attention. I have accepted that sometimes I need to see how something breaks to understand how to make sure it doesn’t break again.

To stay in the game, you have to stay on your toes

A good engineer works around the fact that change happens relatively slowly in this field

It’s not uncommon in engineering for problems to mutate at a rate that is faster than solutions are developed. Innovation simply doesn’t occur fast enough, and, even in cases where a lot of money is invested in research to keep the pace of innovation high, those innovations are not adopted fast enough.

For example, while the technology used to treat wastewater has remained largely the same for over a century, the composition of the wastewater being treated has changed drastically in that period. This has caused a lot of problems for the environment and we are now forced to react, a reaction that is many years overdue.

The cause of all this is that huge infrastructure networks lead to natural monopolies, where it becomes more cost-effective to have one player rather than multiple. Unfortunately, this has also meant that that one player has no competition and, therefore, little incentive to innovate. Thus, wastewater utilities have had little to nothing pushing them to innovate. As long as the environment is able to take the effluent, there is no reason to make changes.

A good developer, by contrast, works to keep up with rapid innovation

Because aggressive competition drives rapid innovation and continuously changing approaches in software development, there is little room for anyone to form a sustainable monopoly for significant periods of time. While it’s not unheard of, it’s rare. The most popular technologies that become ubiquitous at certain periods don’t remain that way for very long before someone comes up with the next big thing. No one can comfortably own space for long unless they understand that they need to stay on their toes in order to stay relevant.

I experienced this when I set out to learn React and React Native in the past year. In 2018 alone there were so many releases of these programs, with each one bringing in new features, fixing bugs and improving old functionalities. Everything just kept changing and improving!

As a result, while I can create some pretty complex React components, I have never really gotten to a point where I feel like I know the ins and outs of React. I was uncomfortable with that initially, but I’ve learned to be okay with it. Always knowing that there’s something I don’t know yet keeps me learning as I try to keep up with the pace of innovation.

How this influenced me as a software developer

I have learned that no solution is ever really complete in software development — there is always something that can be improved.
I have adopted the mindset that once we have met our target and shipped the product, it is time for us to relook at our solution and think about where we can innovate.
I have realized that there is a continuous need to improve performance, increase efficiency, provide better user experience, etc. In development, as soon as something is complete, it is time to take it apart and rethink it.
Knowing that the technology around me is always changing keeps me excited about software development every day.

Your thoughts?

I believe there is a lot that we can learn, not just from civil engineers who became software developers but from lawyers, doctors, taxi drivers and dozens of other professions. Have you come into software development from a completely different background? What have you learned? I’d love to hear from you.

Why work doesn't happen at work - Some perspectives on remote work

Bhekani Khumalo — Fri, 26 Jul 2019 13:16:45 +0000

Here are some ideas I found interesting in three talks about remote work.

Why work doesn't happen at work | Jason Fried

Why is it that people can't seem to get work done at work?

Companies typically decide that people have to come together to this one place, called "an office" filled with lots of different equipment, to do work. But if you ask people the question, "Where do you go when you really need to get something done?", typically you get three kinds of answers:

A place, location, room, for example, the basement, the extra room in the house, the coffee shop, the library, etc.
A commute, for example, the train, on the plane, in the car, etc.
A time for example early in the morning, late at night, on the weekends etc

You rarely hear someone saying "the office", but companies are spending lots of money on "the office" and making people go to it all the time yet people don't do their best work there.

One idea is that there are too many distractions at the office and it's hard to get sustained periods of uninterrupted work. Your day ends up shredded into small work moments instead of a work day. However, creative people like designers, programmers, writers, engineers, thinkers, etc, generally need long stretches of uninterrupted time to get things done. So short 15 to 30 minute bursts of work (in between interruptions) in the office don't allow for people to really get creative and really think about a problem. It's just enough for some quick ideas. While the workday is generally 8 hours, few people get even 2 hours of uninterrupted time to themselves in the office

This is why when people want to get creative, they do work at home, or they go to the office really early or really late in the day or on the weekends when no one is around or when there's fewer people and hence fewer distractions.

Jason Fried also argues that sleep and work are closely related in that they are both phase/stage-based events and in order to get to the really deep and later stages you need to go through the early ones. If you're disrupted along the process, you often need to restart at the earlier stages. We don't expect people to sleep well if they're interrupted all night and in the same way we shouldn't expect people to work well when they're interrupted all day.

Managers typical say things like, "I don't want people to work at home because there are lots of distractions", or, "If I can't see the person then how do I know they're working". However, distractions at home, on the train or on the weekend are all voluntary, you need to make the decision to leave what you're doing and watch the TV or whatever yet distractions in the office are typically not up to you.

So what can managers do to make the office a better place to work? Jason Fried's suggestions are to:

Have no talk Thursdays, once a month. Even if it's just no talk afternoon of that one Thursday. He argues that getting someone 4 hours of uninterrupted time is the best gift you can give someone in the office. And as you realize the usefulness you could increase it to once a week or more.
Find as many opportunities to replace synchronous/active communication and collaboration like face-to-face, tapping someone on the shoulder, having meetings etc, with more asynchronous/passive communication and collaboration like using things like email, instant messaging, collaboration products, etc which allow people to be interrupted on their own schedule. It's up to you to choose when you want to check that message on skype.

An interesting perspective is that it's not enough to have people who are good at working remote. It can only work if you also have a manager who knows how to manage remote workers effectively

Fluent 2013: Mike Hostetler, "Remote Working Works!"

According to Mike Hostetler, the word work is often used to refer to three different things:

The task that needs to be completed, Someone can say, "I have done the work", referring to the task they needed to perform.
The location where tasks are performed. Someone might say, "I'm going to work", referring to travelling to the location where they perform the tasks.
The level of effort needed to complete the task. Someone could say, "This is quite some work", referring to the fact that a lot of effort will be needed.

Why is this important? In a typical job environment, these are typically prioritized as location first then task then effort. If managers could learn to change this prioritization and focus on the task first rather than the location then tasks would be designed to reduce the requirement for them to be tied to a specific location and more none location-based management strategies would evolve. This would open up a range of possibilities and the concept of remote working easier. Without a manager who's good at this, remote working won't be as efficient as it can be.

Possibly the best part about this is that managers aren't inherently good at managing remote workers (maybe some are) but this is a skill that they can learn as they shift their perspective from viewing work as inherently tight to a location to viewing it as task first.

David Copeland gives some interesting tips for improving remote work that I think is certainly worth considering. Check it out on the link below.

The Effective Remote Developer

Do you relate with any of this? Do you agree with the perspectives? What are your thoughts on the ideas? Let's have a discussion in the comments.