Vladimír Zdražil Posts

You don’t need that complexity: A fresh look at your project

Vladimír Zdražil — Fri, 02 Jun 2023 14:21:11 +0000

When you’re working on a project for a long time, you might start to believe that a lot of complexity is needed when it really isn’t. Sometimes, you might even stop noticing it. How can you stop assuming things have to be complex and start finding ways to make your work easier?

Definitions

First, here are definitions of some terms I’ll be using. Feel free to skip them if you’re already familiar with them.

The definitions of essence and accidental parts are paraphrased from No Silver Bullet—Essence and Accident in Software Engineering by Frederick P. Brooks, Jr. (1987).

Software entity

The term software entity refers to any software product or artifact. This could be a full application, a software library, a module, or even a single function or method, depending on the context. It’s an entity in the sense that it exists as a distinct, identifiable object.

Essence of a software entity

The essence of a software entity is an abstract construct of interlocking concepts: data sets, relationships among data items, algorithms, and invocations of functions.

The essence is abstract, in that the construct is the same under many different representations. It is nonetheless highly precise and richly detailed.

It’s the essence because it’s inherent to the nature of the software entity. It can’t be eliminated or simplified by any technology or technique.

Accidental aspect of a software entity

Accidental aspect of a software entity is the specific representation of the essence and the mapping of it onto machine languages within space and speed constraints. Where essence is an abstract construct, the accidental aspect is a concrete representation.

It’s accidental because it’s not inherent to the nature of the software entity. You can eliminate or simplify it by different technologies and techniques. You can come up with a representation that is less complex, but you can’t make the essence less complex.

Essential complexity and difficulties

Essential complexity and difficulties that are inherent in the nature of the software.

Accidental complexity and difficulties

Difficulties and complexity that accompany software production but that are not inherent.

Fred Brooks (1987) believes that the hard part of building software is the specification, design, and testing of the essence, not the labor of representing it and testing the fidelity of the representation.

Looking at complexity in a new way

Reading through this topic made me think about how, sometimes, when we work on a project for a while, we start to believe that many things are essential complexity when they actually aren’t.

What if we periodically looked at our projects like they’re brand new? Consider if you could start your project over. What would you do differently? What choices would you make? What would you not do?

Sure, some things are accidental complexity, but you can’t practically change them. Be it for technical, political or other reasons. For example, it’s not very realistic that you’ll avoid using CSS as a frontend developer. But even then, when was the last time you checked? Maybe it’s now possible to actually do something about it?

Or perhaps you’re using a tool because everyone else is, but it’s making your work harder. Everyone suggests using Redux? You don’t necessarily have to. Everybody advocates strict TypeScript rules? That’s not a mandate either. JavaScript is making things complicated? Maybe you could use ClojureScript?

No supreme deity of programming will penalize you for venturing off the beaten path. Carefully weigh the pros and cons, understand why the established tools are there, and then make your own decision.

Let’s not be caught in the illusion that certain complexities are unavoidable when they are indeed optional. Take a step back sometimes. Look at your work as if it’s new. You might find a way to make things simpler.

References

Brooks, F. P. (1995a). Chapter 16. No Silver Bullet—Essence and Accident in Software Engineering. In The mythical man-month: Essays on software engineering (Anniversary edition). Addison-Wesley Publishing Company.
Brooks, F. P. (1995b). Chapter 17. “No Silver Bullet” Refined. In The mythical man-month: Essays on software engineering (Anniversary edition). Addison-Wesley Publishing Company.
Brooks, F. P. (1986). No Silver bullet—Essence and accidents of software engineering. IEEE Computer, 20(4), 10–19.
Moseley, B., & Marks, P. (2006). Out of the tar pit. Software Practice Advancement (SPA), 2006.

No silver bullet

Option A vs A | null

Vladimír Zdražil — Wed, 03 May 2023 03:45:47 +0000

TLDR

Two common ways to represent absence of a value in TypeScript are A | null and Option<A>. I suggest you use A | null by default and switch to Option<A> only when needed. Such as when you want to use fp-ts utils.

Introduction

When representing the absence of a value in TypeScript, you can use a union type A | null, or a tagged union type Option<A>. In this post, we’ll discuss the differences between these two approaches and when to use each. Keep in mind that this post focuses on TypeScript and other languages may have different considerations.

Untagged union: `A | null`

An untagged union is a type that can hold values of different types, but it doesn’t provide any information about which type is actually present. In TypeScript, you often use the untagged union A | null to represent a value that may or may not be present.

/** This example demonstrates the use of an untagged union. */
function getFirstLetter(str: string): string | null {
  if (str.length > 0) {
    return str.charAt(0);
  } else {
    return null;
  }
}

console.log(getFirstLetter("hello")); // Output: "h"
console.log(getFirstLetter("")); // Output: null

Tagged union: `Option<A>`

A tagged union is a type that can contain one of several different types, but it does provide additional information to differentiate between them. It is a subset of the more general concept of a union.

In TypeScript, Option<A> is an example of a tagged union that represents a value that may or may not be present. You might also know tagged union under names such as variant, variant record, choice type, discriminated union, disjoint union, sum type or coproduct.

import { option } from "fp-ts";
import { Option } from "fp-ts/Option";

/** This example demonstrates the use of a tagged union. */
function getFirstLetter(str: string): Option<string> {
  if (str.length > 0) {
    return option.some(str.charAt(0));
  } else {
    return option.none;
  }
}

console.log(getFirstLetter("hello")); // Output: { _tag: 'Some', value: 'h' }
console.log(getFirstLetter("")); // Output: { _tag: 'None' }

What about `Maybe<A>`?

Option and Maybe are the same concept, meaning that when I’m referring to Option<A>, you can consider it synonymous with Maybe<A>.

What about `A | undefined`?

It’s not worth treating null and undefined as different types. When I say null, you can pretend I mean null | undefined. Ideally, TypeScript and JavaScript would have only undefined. Check out this video for more information, 9:21.

Things to remember

A | null is a union type. It’s untagged.
Option<A> is a union type. It’s tagged.

Comparison: Simplicity and familiarity

Winner: A | null ✅

Untagged union A | null has an advantage of being simple and familiar to many programmers. Most programmers are already familiar with null and imperative code like if (foo != null) to check if a value is present or not.

Option<A> type is not as familiar as A | null. This can make the code more challenging to read and understand, particularly for those who are not well-versed in functional programming concepts.

However, not everything needs to be designed for beginners, as highlighted in this talk by Rich Hickey, 31:54. While using Option<A> may require some additional learnings, the benefits might be worth it.

We should not sell humanity short by trying to solve the problem of beginners in our stuff. We need to make things for people to use, and we need to teach people and trust people to be able to learn how to do that.

Design, Composition, and Performance, 34:23 by Rich Hickey

Comparison: Interop with other platforms, languages and libraries

Winner: A | null ✅

A | null simplifies interop with other platforms and languages that use a similar representation, such as a JSON API that uses null to represent the absence of a value. This can be an advantage in terms of seamless integration between different parts of a codebase or across different systems.

On the other hand, if you use Option<A> and need to interact with a system that uses null to represent absence of a value, you’ll need to convert between Option<A> and null. While this is not necessarily a bad or a hard thing to do, it can add additional complexity and make the code harder to read and maintain.

Comparison: Native language support

Winner: A | null ✅

Another advantage of A | null is that it allows you to use already existing syntax and usability features of Typescript designed for handling absent values.

For example, in TypeScript, there is a null-aware operator (?.) that simplifies checking for null values.

// Demonstrates optional chaining

interface User {
  name: string;
  address?: {
    street: string;
    city: string;
    state: string;
  };
}

const user: User = {
  name: "John Smith",
};

const state = user.address?.state;

console.log(state); // Output: undefined

In TypeScript, Option<A> does not have any special language support, which can make the code more verbose and harder to read.

Comparison: `fp-ts`

Winner: Option<A> ✅

TypeScript needs a utility library, and the best one available is fp-ts. It provides patterns and reliable abstractions from typed functional languages, including Option<A>.

While fp-ts can interop with A | null, Option<A> is the preferred abstraction for absence of a value and your code will be less verbose if you use Option<A>.

Comparison: Support of functional patterns aka nesting of types

Winner: Option<A> ✅

An advantage of using a tagged union like Option<A> is that it allows nesting of types. Untagged union A | null can’t do that.

Support for nested types is important for many functional patterns because it allows computations to be composed in a predictable and composable way.

Without support for nested types, it can be difficult or impossible to implement some functional patterns, or they may require workarounds that make the code more complex and error-prone.

Example 1

If you write code that works with any type A, without knowing its specific context, you will need a support for nested types, because in that case you may end up with something akin to Option<Option<A>> and you most probably should not collapse that type to keep the behavior consistent.

You can’t do that with untagged union A | null. In many concrete contexts, you could probably simplify Option<Option<A>> to just Option<A>, but not in the generic one.

As a concrete example, consider the type of custom tryCatch:

Implemented with `Option<A>`

import { Option } from "fp-ts/Option";
import { option } from "fp-ts";

const tryCatch = function <A>(f: () => A): Option<A> {
  try {
    return option.some(f());
  } catch (e) {
    return option.none;
  }
};

const result1: Option<Option<number>> = tryCatch(() => {
  const num: Option<number> =
    Math.random() < 0.5 ? option.some(42) : option.none;
  return num;
});

const result2: Option<Array<number>> = tryCatch(() => {
  const arr: Array<number> = Math.random() < 0.5 ? [1, 2, 3] : [3, 5, 6];
  return arr;
});

Implemented with `A | null`

const tryCatch = function <A>(f: () => A): null | A {
  try {
    return f();
  } catch (e) {
    return null;
  }
};

const result1: number | null = tryCatch(() => {
  const num: number | null = Math.random() < 0.5 ? 42 : null;
  return num;
});

const result2: Array<number> | null = tryCatch(() => {
  const arr: Array<number> = Math.random() < 0.5 ? [1, 2, 3] : [3, 5, 6];
  return arr;
});

Comparison

Notice the types you receive after calling tryCatch. When using Option<A>, everything is consistent. We treat A as untouchable, simply putting it inside an Option.

However, with A | null, if you give us an A that happens to be null, we just give you null back instead of wrapping it in an Option. This means that A is no longer untouchable, and if A happens to be null, the type is collapsed.

As a caller, you won’t be able to tell if the function failed or if the returned null is a result of absence of a value.

Example 2

In fp-ts, the traverse method is a commonly used function with a predictable behavior that users expect. For example, if you know how array.traverse works, you can likely predict the behavior of option.traverse.

However, if you’d implement option.traverse with A | null, it would behave differently than other traverse functions, making it harder to understand.

To prevent confusion, it’s better to use Option<A> instead of A | null. By doing so, you ensure that everything behaves consistently.

Example 3

Let’s say you’re trying to retrieve a user address by their ID, but they may or may not have an associated address.

interface User {
  id: string;
  address: string | null;
}

type Users = Record<string, User>;

In this situation, you can encounter three possible outcomes:

There is no user with the specified ID.
There is a user with the specified ID, but they do not have an address.
There is a user with the specified ID, and they have an address.

If you use the A | null representation to handle these outcomes, you would get the following results:

null
null
address

As a result, you lose information about whether or not you found a user. However, if you use the Option<A> representation instead, you get more detailed results:

None
Some(None)
Some(Some(address))

This representation allows you to retain more information about whether or not you found a user, and whether or not they have an associated address.

Comparison: Flexibility and backwards compatibility

Winner: A | null ✅

Inspired by Rick Hickey‘s presentation Maybe not, 7:43, the following scenario explores the different outcomes of representing absent values.

Consider this scenario:

You create a function with the interface (text: string) => string.
It starts to get used in multiple places.
As it evolves you decide that this function should also handle absence of a value.

Now one of 2 things will happen, depending on what you picked for representation of absent value.

1. `string | null`

You change the interface to (text: string | null) => string. And you’re done. This change doesn’t break any callers.

2. `Option<string>`

You change the interface to (text: Option<string>) => string. Well, this change breaks all callers.

Ok, let’s fix that and change it to (text: string | Option<string>) => string. This option is also problematic because it’s a poor interface, and it’s clear that we created it only for backwards compatibility.

The clean approach is to use (text: Option<string>) => string and rewrite all the callers accordingly.

Result

As you can see, using string | null as the representation of absent values provides more flexibility in this regard. This applies also to a more generic A | null.

Comparison: Performance

While it’s also possible to compare the performance of Option<A> and A | null (see details), this article focuses only on the usability of the two approaches.

When to use `A | null` vs `Option<A>`

Now that we’ve looked at the advantages and disadvantages of both A | null and Option<A>, let’s explore when to use each one. Use A | null when:

You have a simple use case where the absence of a value is not nested.
You’re working with code that’s not heavily influenced by functional programming patterns.
You’re interacting with other platforms and languages that use null to represent the absence of a value.

Use Option<A> when:

You need to represent nested absences.
You’re working in a functional programming context.
You want to use the fp-ts utilities which use Option<A> as an abstraction for the absence of a value.

No really, which one is better?

My recommendation is to default to using A | null and only switch to Option<A> when necessary, limiting its use to a closely related code. It’s going to result in a simpler and more familiar codebase and makes it easier to interact with modules that don’t use fp-ts.

While using A | null means you lose the ability to nest nullability, from my experience, nested absent values are not very common. Therefore, this limitation is not as significant as you might think.

Moreover, even in cases where nesting is required, using nested optionals can make the interface harder to use and understand and you might consider refactoring it.

And if refactoring is not possible, it’s very simple to convert from A | null to Option<A> with fp-ts utils fromNullable and toNullable:

import { option } from "fp-ts";
import { Option } from "fp-ts/Option";
import { pipe } from "fp-ts/function";

// Converting nullable to Option
const hello = "hello";
const nullableValue: string | null = hello;
const optionValue: Option<string> = option.fromNullable(nullableValue);

// Converting Option to nullable
const optionValue2: option.Option<string> = option.none;
const nullableValue2: string | null = option.toNullable(optionValue2);

// More practical example, with the use in `pipe`
const result1: option.Option<number> = pipe(
  nullableValue,
  option.fromNullable,
  option.map((value) => value.length),
);

const result2: number | null = pipe(
  optionValue2,
  option.map((value) => value.length),
  option.toNullable,
);

Conclusion

In conclusion, TypeScript offers two popular options for representing the absence of a value: using an untagged union type A | null or a tagged union type Option<A>.

While the former is simpler and more familiar to many programmers, the latter is more consistent and better supports many functional patterns.

In my opinion, it’s best to default to using A | null and only switch to Option<A> when necessary. This could be for a variety of reasons, such as wanting to use fp-ts utils.

However, it’s not a strict rule and use whichever option makes the most sense for your situation.

chris20194. (2020, July 26). Explicit nullability vs optionals [Reddit Post]. R/ProgrammingLanguages.
Crockford, D. (2014, September 18). The Better Parts. Nordic.js 2014, Artipelag, Stockholm.
evincarofautumn. (2020, July 26). Nullability is *idem… [Reddit Comment]. R/ProgrammingLanguages.
Eh, that’s a tagged union, but I think “union type” usually refers to untagged u…. (2014, December 10). Hacker News.
Hickey’s Maybe example feels misguided (about breaking existing callers). If M…. (2018, November 30). Hacker News.
Hickey, R. (2013, April 2). Design, Composition, and Performance. ETE 2013, Philadelphia Sheraton, Society Hil, USA.
Hickey, R. (2018, November 30). Maybe Not. Clojure Conj 2018, Durham, NC, USA.
Incorporate monads and category theory. (2022, May 12). GitHub.
Isn’t Union Types just the same as “Sum Types” (as in Haskell etc.)? But does Ha…. (2022, July 7). Hacker News.
Khan, W. (2017, July 24). Null-tracking, or the difference between union and sum types. Steno & PL.
Lee, R. (2020, October 1). Practical Guide to Fp-ts P5: Apply, Sequences, and Traversals. Ryan’s Blog.
munificent. (2020b, July 26). The typical answer i… [Reddit Comment]. R/ProgrammingLanguages.
Option type. (2023). In Wikipedia.
PrimaryBet. (2020a, March 11). PrimaryBet comments on Why use Some('a) rather than ’a? [Reddit Post]. R/Reasonml.
PrimaryBet. (2020b, August 28). One big difference b… [Reddit Comment]. R/Typescript.
Spar, J. (2017, August 16). Why are Promises Monads? [Forum post]. Stack Overflow.
Spec Preview: Union types. (2015, October 28). GitHub.
Suggestion: Change the internals of Option type. (2020, October 23). GitHub.
stepstep. (2020, July 27). To all the people sa… [Reddit Comment]. R/ProgrammingLanguages.
Tagged union. (2023). In Wikipedia.
TypeScript Documentation contributors. (2023, May 1). Documentation—Everyday Types [Documentation]. TypeScript: Documentation.
Union type. (2023). In Wikipedia.
Wayne, H. (2023, March 6). Unions are Untagged, and should be Discriminated in TypeScript: Undecidable, collapse, and anti-patterns. Hackle’s Blog.
Zaitsev, D. (2018, May 4). Answer to “Why are Promises Monads?” Stack Overflow.

Deep and shallow modules: Module design for reduced complexity

Vladimír Zdražil — Sat, 15 Apr 2023 19:02:34 +0000

Updates

2023-05-28: Added TypeScript example.

TLDR

To keep complexity in check, prefer deep modules to shallow modules. A deep module has a lot of functionality hidden behind a simple interface. A shallow module has a relatively complicated interface, but doesn’t provide much functionality behind it.

Introduction

In this post, we’ll take a look at one of the ways to design modules in a manner that reduces complexity in your code base. By the end of it, you’ll be equipped with the knowledge you need to make your projects a bit easier to work with.

This article draws its ideas from the book A Philosophy of Software Design by John Ousterhout, particularly from the chapter on Deep modules. I highly recommend reading this book.

Here’s what we’re going to cover:

Definitions

What’s a module

A module is a relatively independent entity that can take many forms, such as classes, services, functions, or subsystems. It consists of an interface (the what) and an implementation (the how).

What’s an abstraction

An abstraction is a simplified view of an entity, which omits unimportant details. This makes it easier to think about and manipulate such an entity.

What’s an interface

Each module has an interface which serves as the module’s abstraction. This abstraction presents a simplified view of the module’s functionality. You can interact with the module through this abstraction without needing to know the implementation details.

The module interface contains essential information you need to use a module effectively. It consists of two kinds of information:

Formal interface information

Formal interface information is specified explicitly in code, and some of it can be checked for correctness by your programming language.

For example, the formal interface of a method is expressed in its signature, which includes the parameter names, types and the return value’s type.

Informal interface information

Informal interface information describes behaviors and usage restrictions that cannot be enforced and described by the programming language. They can only be described through comments, and they are usually more complicated than the formal information.

Examples could be description of the limitations or known issues with the module.

What’s an implementation

Implementation is the actual code that does what the module’s interface promised. It’s all the technical stuff behind the scenes, like algorithms and data structures, that achieves what the interface described.

Avoid complexity by considering the cost and benefit of modules

Adding a module to your codebase introduces complexity because it adds another thing you need to understand and integrate with existing code.

The cost associated with a module is primarily its interface. As a user of the module, you do not need to know its implementation details, only how to interact with its interface. The smaller and simpler the interface, the less complexity the module introduces.

The benefit associated with a module is the additional functionality it provides to your program.

To avoid complexity, you need to consider the cost and benefit associated with each module. The cost primarily relates to the complexity the module’s interface is introducing, while the benefit comes from the additional functionality the module provides.

Deep and shallow modules

By comparing the functionality and interface of modules, which we described in terms of cost vs. benefit, you can categorize modules into two types:

A module’s depth refers to the amount of functionality it has hidden behind an interface. The more functionality there is hidden behind an interface, the deeper the module is.

Deep modules

A deep module has a lot of functionality hidden behind a simple interface.

Shallow modules

A shallow module has a relatively complicated interface, but doesn’t provide much functionality behind it. In extreme cases, a module can be so shallow that it adds no abstraction — using it requires more documentation and effort than just directly manipulating the variable it’s supposed to modify.

Deep and shallow modules figure

                 interface/cost
             ┌─ (less is better)
             │ │
             │ │
             │ │
             │ │
             │ │                   functionality/benefit
 ■■■■■■■■■■■◀┘ │      ┌───────────── (more is better)
 │          │  │      │
 │          │  │      │                           │
 │          │  │      │                           │
 │          │  │      │                           │
 │          │  │      │              ┌────────────┘
 │       ◀─────┼──────┘              │
 │          │  │                     │
 │          │  │                     │
 │          │  │                     │
 │          │  └───▶■■■■■■■■■■■■■■■■■│■■■■
 │          │      │                 ▼   │
 │          │      │                     │
 └──────────┘      └─────────────────────┘
 deep module           shallow module

To keep complexity in check, prefer deep modules

The best modules are those that offer significant benefits while keeping the costs low. Deep modules are an example of this, as they offer a lot of functionality behind a simple interface, while imposing the least amount of complexity on the system.

On the other hand, shallow modules don’t help much in managing complexity, as they offer little to no abstraction and make things more complicated. In other words, they add complexity but provide no compensating benefit.

When you’re adding a module, do a cost-benefit analysis. Ask yourself if the module provides enough benefit (functionality) compared to its cost (interface). By thinking in terms of deep modules, you can ensure that you’re adding modules that offer significant benefits while keeping the costs low.

TypeScript example

Examples

This TypeScript example demonstrates the concepts of shallow and deep modules. The code is organized into separate modules represented by region comments.

In the first example, we have several shallow modules. In the second example, I’ve refactored the code to reduce the number of those shallow modules.

Feel free to dig in, play around with it, and ask yourself: Which example is easier to understand and maintain? Which one introduces more complexity?

Example with shallow modules

/**
 * Pretend that each region comment represents a separate module.
 *
 * By keeping everything in one file, it's easier to experiment with the example
 * in a REPL.
 */

/* #region Module `types.ts` */

type State = {
  cancellationPolicies: CancellationPolicy[];
  prices: ProductPrice[];
  productGroups: ProductGroup[];
};

/* #endregion */

/* #region Module `cancellationPolicy.ts` */

type CancellationPolicy = {
  absoluteFee: number;
  relativeFee: number;
  productId: string;
};

const getCancellationPolicies = (state: State) => state.cancellationPolicies;

const getProductCancellationPolicies = (state: State, productId: string) => {
  const policies = getCancellationPolicies(state);
  return policies.filter((policy) => policy.productId === productId);
};

const isCancellationPolicyFree = ({
  absoluteFee,
  relativeFee,
}: CancellationPolicy) => absoluteFee === 0 && relativeFee === 0;

const isSomeProductCancellationPolicyFree = (
  state: State,
  productId: string,
) => {
  const policies = getProductCancellationPolicies(state, productId);
  return policies.some(isCancellationPolicyFree);
};

const hasProductGroupFreeCancellation = (state: State, productIds: string[]) =>
  productIds.some((productId) =>
    isSomeProductCancellationPolicyFree(state, productId),
  );

/* #endregion */

/* #region Module `productPrice.ts` */

type ProductPrice = {
  productId: string;
  productGroupId: string;
  value: number;
};

const getProductPrices = (state: State): ProductPrice[] => state.prices;

const getProductGroupPrices = (state: State, productGroupId: string) => {
  const prices = getProductPrices(state);
  return prices.filter((prices) => prices.productGroupId === productGroupId);
};

const getPriceProductIds = (productPrices: ProductPrice[]) =>
  productPrices.map((price) => price.productId);

/* #endregion */

/* #region Module `productGroup.ts` */

type ProductGroup = {
  id: string;
  name: string;
};

const getProductGroups = (state: State) => state.productGroups;

const getProductGroup = (state: State, id: string) => {
  const productGroups = getProductGroups(state);
  return productGroups.find((productGroup) => productGroup.id === id);
};

/* #endregion */

/* #region Module `productGroupView.ts` */

function getProductGroupData(state: State, productGroupId: string) {
  const productGroup = getProductGroup(state, productGroupId);

  if (productGroup == null) {
    return undefined;
  }

  /* #region We’re going to refactor these callers and callees in the second example. */
  const productGroupPrices = getProductGroupPrices(state, productGroupId);
  const productIds = getPriceProductIds(productGroupPrices);
  const hasFreeCancellation = hasProductGroupFreeCancellation(
    state,
    productIds,
  );
  /* #endregion */

  return {
    id: productGroupId,
    hasFreeCancellation,
    name: productGroup.name,
  };
}

/* #endregion */

// #region Module `main.ts`

const productId1 = "productId1";
const productId2 = "productId2";
const productId3 = "productId3";

const productGroupId1 = "productGroupId1";
const productGroupId2 = "productGroupId2";
const productGroupId3 = "productGroupId3";

/**
 * Assume that you cannot change the returned state.
 *
 * We could restructure the state to make it easier to achieve our desired
 * outcome, but in longer-term projects, that task might not be as
 * straightforward.
 */
function getState(): State {
  return {
    cancellationPolicies: [
      { absoluteFee: 25, productId: productId1, relativeFee: 0 },
      { absoluteFee: 0, productId: productId2, relativeFee: 0 },
      { absoluteFee: 32, productId: productId3, relativeFee: 0 },
    ],
    productGroups: [
      { id: productGroupId1, name: "Product group 1" },
      { id: productGroupId2, name: "Product group 2" },
    ],
    prices: [
      { productGroupId: productGroupId1, productId: productId1, value: 36 },
      { productGroupId: productGroupId1, productId: productId2, value: 45 },
      { productGroupId: productGroupId2, productId: productId3, value: 47 },
    ],
  };
}

function main() {
  const state = getState();

  console.log(getProductGroupData(state, productGroupId1));
  console.log(getProductGroupData(state, productGroupId2));
  console.log(getProductGroupData(state, productGroupId3));
}

main();

/* #endregion */

Example refactored based on the idea of deep modules

I’ve kept the root selectors in each module and have not refactored hasProductGroupFreeCancellation to directly access the state. In our example, it doesn’t matter if we access the state directly, but in larger projects, it might be a good idea to encapsulate the state shape.

/**
 * Pretend that each region comment represents a separate module.
 *
 * By keeping everything in one file, it's easier to experiment with the example
 * in a REPL.
 */

/* #region Module `types.ts` */

type State = {
  cancellationPolicies: CancellationPolicy[];
  prices: ProductPrice[];
  productGroups: ProductGroup[];
};

/* #endregion */

/* #region Module `cancellationPolicy.ts` */

type CancellationPolicy = {
  absoluteFee: number;
  relativeFee: number;
  productId: string;
};

const getCancellationPolicies = (state: State) => state.cancellationPolicies;

/* #endregion */

/* #region Module `productPrice.ts` */

type ProductPrice = {
  productId: string;
  productGroupId: string;
  value: number;
};

const getProductPrices = (state: State): ProductPrice[] => state.prices;

/* #endregion */

/* #region Module `productGroup.ts` */

type ProductGroup = {
  id: string;
  name: string;
};

const getProductGroups = (state: State) => state.productGroups;

const getProductGroup = (state: State, id: string) => {
  const productGroups = getProductGroups(state);
  return productGroups.find((productGroup) => productGroup.id === id);
};

/* #endregion */

/* #region Module `productGroupView.ts` */

function hasProductGroupFreeCancellation(state: State, productGroupId: string) {
  const productIds = getProductPrices(state)
    .filter((prices) => prices.productGroupId === productGroupId)
    .map((price) => price.productId);

  /**
   * When you start putting things closer together, as we did here, you might
   * start seeing opportunities for refactors you haven't seen before.
   *
   * For example, in this case, I removed the nested `some` and used `includes`
   * instead.
   */
  const cancellationPolicies = getCancellationPolicies(state);
  const matchedPolicies = cancellationPolicies.filter(
    ({ productId, absoluteFee, relativeFee }) =>
      absoluteFee === 0 && relativeFee === 0 && productIds.includes(productId),
  );

  return matchedPolicies.length > 0;
}

function getProductGroupData(state: State, productGroupId: string) {
  const productGroup = getProductGroup(state, productGroupId);

  if (productGroup == null) {
    return undefined;
  }

  // Callers and callees are refactored.
  const hasFreeCancellation = hasProductGroupFreeCancellation(
    state,
    productGroupId,
  );

  return {
    id: productGroupId,
    hasFreeCancellation,
    name: productGroup.name,
  };
}

/* #endregion */

// #region Module `main.ts`

const productId1 = "productId1";
const productId2 = "productId2";
const productId3 = "productId3";

const productGroupId1 = "productGroupId1";
const productGroupId2 = "productGroupId2";
const productGroupId3 = "productGroupId3";

/**
 * Assume that you cannot change the returned state, for example, because it
 * comes from a third-party API.
 */
function getState(): State {
  return {
    cancellationPolicies: [
      { absoluteFee: 25, productId: productId1, relativeFee: 0 },
      { absoluteFee: 0, productId: productId2, relativeFee: 0 },
      { absoluteFee: 32, productId: productId3, relativeFee: 0 },
    ],
    productGroups: [
      { id: productGroupId1, name: "Product group 1" },
      { id: productGroupId2, name: "Product group 2" },
    ],
    prices: [
      { productGroupId: productGroupId1, productId: productId1, value: 36 },
      { productGroupId: productGroupId1, productId: productId2, value: 45 },
      { productGroupId: productGroupId2, productId: productId3, value: 47 },
    ],
  };
}

function main() {
  const state = getState();

  console.log(getProductGroupData(state, productGroupId1));
  console.log(getProductGroupData(state, productGroupId2));
  console.log(getProductGroupData(state, productGroupId3));
}

main();

/* #endregion */

Conclusion

When designing modules, consider the balance between the cost and benefit associated with each module. To keep complexity in check, generally prefer deep modules over shallow modules.

Deep modules provide a lot of functionality behind a simple interface, while shallow modules have a relatively complicated interface but do not provide much functionality. By choosing deep modules, you can ensure that you are adding significant benefits to your codebase while keeping complexity lower.

Book and book chapter — Ousterhout, J. K. (2022). Deep modules. In A philosophy of software design (Second edition). Yaknyam Press.
Talk — Ousterhout, J. (2018, August 1). A Philosophy of Software Design. Talks at Google.
Google Talk Forum — Ousterhout, J. (2018, May 24). Software-Design-Book Google Talk Forum.
Lecture notes – Ousterhout, J. (2018). Modular Design—Lecture Notes for CS 190. CS 190: Software Design Studio (Winter 2018)
Article — P. Gabriel, R. (1991). Worse Is Better.
- Simplicity – the design must be simple, both in implementation and interface. It is more important for the interface to be simple than the implementation.
This review is interesting because the reviewer disagrees with some points of the book. Personally, I’m still siding with points expressed in the book:
- Koppel, J. (2018, October 29). Book Review: A Philosophy of Software Design. Path-Sensitive.
- Koppel, J. (2018, October 8). Book Review: A Philosophy of Software Design. Software-Design-Book Google Talk Forum.

Philosophy of software design (2018) — John Ousterhout

Binary search debugging: Simplify your debugging process

Vladimír Zdražil — Fri, 07 Apr 2023 13:49:16 +0000

Introduction

Tracking down bugs in your code is often frustrating. With a binary search debugging you can make it less so. It’s a simple technique that can help you pinpoint problematic lines of code quickly and efficiently.

What is binary search debugging?

Binary search debugging is a methodical process that aims to narrow down the cause of a bug by systematically testing different parts of the code. The name “binary” refers to the fact that at each step, you divide the code that you suspect is causing the problem in the middle and evaluate its behavior, typically using a breakpoint or a print statement.

After each evaluation, you choose a new breakpoint closer to the suspected problem area and repeat the process until you pinpoint the single line of code responsible for the bug.

Step-by-step guide

Identify the problem
- The first step in debugging any piece of code is to identify the problem. Determine the exact behavior that is not working as intended.
Choose a breakpoint
- Decide where to place the breakpoint. This should be a line of code that is close to the middle of the section of code you suspect is causing the problem.
Run the code with the breakpoint in place.
Determine the result
- Does the code behave as expected at this breakpoint?
Choose a new breakpoint
- Choose a new breakpoint that is located midway between the previous breakpoint and the start or end of the section of code, depending on the result of the previous run.
Run the code and evaluate again.
Repeat steps 3-6 until you have narrowed down the section of code causing the issue to a single line.

Different name, same thing

Binary search debugging is a technique that uses the binary search algorithm. However, instead of searching for a specific value, you are looking for the side effect of a value, such as an error or unexpected behavior in your code.

Sometimes, people refer to this approach as the Wolf Fence algorithm, named after a hypothetical scenario where you need to find a lone wolf in Alaska. To do so, you fence Alaska in half and wait for the wolf to howl. Once you know which half the wolf is in, you repeat the process, splitting the section in half again until you find the wolf.

Another term used to describe this technique is bisection or divide and conquer.

Benefits

It helps you find bugs in your code faster.
You’re less likely to miss something since you’re being methodical.
It breaks the debugging process into smaller, easier-to-manage chunks.
It’s super easy to use, you don’t need any fancy tools or software.

Drawbacks

Limited to specific types of bugs
- Binary search debugging is most effective for bugs that are easily reproducible and have a clear input/output. Bugs that are more intermittent or related to external factors may be more difficult to isolate using this technique.
- It may not be effective for bugs that occur in things that are executed multiple times. Like loops.
Requires familiarity with the codebase
- Binary search debugging assumes that you have a good understanding of the codebase and can identify which sections of the code to isolate.

Conclusion

Binary search debugging is a technique that can help you locate and resolve bugs in software projects more efficiently. The approach involves repeatedly dividing the codebase into smaller sections to narrow down the buggy lines faster. By isolating and testing each section systematically, you can quickly pinpoint problematic lines of code and resolve the issue more efficiently.

Did you know?

Git uses this algorithm for the command git bisect to determine which commit introduced a particular bug.

C2 Wiki Contributors. (2006, October 11). Binary Chop. C2 Wiki.
Gauss, E. J. (1982). The “Wolf Fence” algorithm for debugging. Communications of the ACM, 25(11), 780.
unj2. (2010, May 19). Debugging and Binary Search [Forum post]. Stack Overflow.

Why Object.keys doesn’t and shouldn’t return (keyof T)[]

Vladimír Zdražil — Sun, 02 Apr 2023 10:22:14 +0000

TLDR

Object.keys() doesn’t return (keyof T)[] in TypeScript because objects can have additional properties at runtime, leading to potential issues. Use wrapper as a workaround and be aware of the limitations when using it.

Introduction

Have you ever wondered why Object.keys doesn’t return type (keyof T)[] in TypeScript? In this article, we’ll explore the reasons behind this decision and look at some examples to illustrate the potential issues with returning (keyof T)[].

Overview of `Object.keys()`

In TypeScript, Object.keys() is a built-in method that returns an array of a given object’s own enumerable string-keyed property names:

// Object.keys(obj: object): string[];

interface Person {
  name: string;
  age: number;
}

const person: Person = {
  name: "John Doe",
  age: 35,
};

const result = Object.keys(person); // return type is string[]

console.log(result); // ["name", "age"]

Why `Object.keys()` doesn’t return `(keyof T)[]`?

The reason Object.keys() doesn’t return type (keyof T)[] in TypeScript is that once you move to the instantiated type world, an object can have more properties at runtime than are statically known at compile time. As a result, returning (keyof T)[] makes sense only in the domain of type variables, such as T and keyof T.

Anders Hejlsberg, a core developer of TypeScript, explained this in a comment on GitHub.

All this goes back to the reasoning why TypeScript uses structural type system. You can’t know that JavaScript object won’t have additional properties. If TypeScript supported exact types, it would make sense to use (keyof T)[]. But TypeScript doesn’t have them.

Hejlsberg also gave an example to illustrate his point:

For example, imagine a type Base with just a few properties and a family of types derived from that. Calling Object.keys with a Base would return a (keyof Base)[] which is almost certainly wrong because an actual instance would be a derived object with more keys. It completely degenerates for type {} which could be any object but would return never[] for its keys.

Object.keys() types refinement, and Object.entries() types bug fix — ahejlsberg Nov 27, 2016

In the following section, we’ll explore some code examples to see what could go wrong if Object.keys() did return (keyof T)[].

Example 1

Pretend that Object.keys() does return (keyof T)[] and consider this example:

type TaskCategory = "work" | "home";
type TaskCounts = Record<TaskCategory, number>;

function logCategoryCounts(counts: TaskCounts) {
  const categoryNames = Object.keys(counts);
  console.log("Task categories:", categoryNames);
}

const taskCounts = { work: 10, home: 5, personal: 3 };

logCategoryCounts(taskCounts);

This is what the return type is and what is logged:

const categoryNames = Object.keys(counts); // categoryNames type is ["work" | "home"]
console.log("Task categories:", categoryNames); // logs ["work" | "home" | "personal"]

There’s a mismatch between what we logged and what the types said.

This is allowed due to TypeScript’s use of a structural type system.

Example 2

Again, pretend that Object.keys() does return (keyof T)[]. This example demonstrates how Object.keys() would return the wrong never[] type.

function logCategoryCounts(counts: {}) {
  const categoryNames = Object.keys(counts); // categoryNames type is never[]
  console.log("Task categories:", categoryNames); // logs ["work" | "home"]
}

const taskCounts = { work: 10, home: 5 };

logCategoryCounts(taskCounts);

Example 3

Consider this code:

const windowKeys = Object.keys(window);
console.log(windowKeys);

We have no way of knowing whether the window object has been mutated, or if the browser’s window has more properties than what our types indicate. This means that it could potentially have properties that weren’t known at compile time. Assuming that Object.keys() does return (keyof T)[], Object.keys() return type could be incorrect.

I understand all this, but I still want to do it

If you still want to use return type (keyof T)[] for Object.keys(), you can create a wrapper around it like so:

/**
 * A wrapper for `Object.keys()` that forces a `(keyof T)[]` return type.
 * Warning: using this wrapper may lead to potential issues if the object being
 * passed in has additional properties that aren't known at compile time. Please
 * use with caution and ensure that you're aware of the limitations of this
 * approach.
 * [https://stackoverflow.com/a/55012175](https://stackoverflow.com/a/55012175)
 */
export const keys = Object.keys as <T>(o: T) => Extract<keyof T, string>[];

Object.keys() types refinement, and Object.entries() types bug fix — domoritz Jun 1, 2018

However, it’s important to be aware of the potential drawbacks of using this type of wrapper, so consider adding a warning message to it.

Conclusion

We explored why TypeScript doesn’t return type (keyof T)[] when using Object.keys(). This decision stems from the fact that objects can have more properties at runtime than what is known at compile time. Returning (keyof T)[] would be misleading and could potentially cause issues.

You saw some examples of how this could happen and saw a wrapper for a workaround. It is important to understand the reasoning behind this decision and consider the potential drawbacks when working with returning (keyof T)[].

Cavanaugh, R. (2019a, March 5). Why doesn’t Object.keys return a keyof type in TypeScript? [Forum post]. Stack Overflow.
Cavanaugh, R. (2019b, March 5). Answer to “Why doesn’t Object.keys return a keyof type in TypeScript?” Stack Overflow.
Flow Documentation Contributors. (2023, May 1). Object Types. Flow Documentation.
Hejlsberg, A. (2016, November 27). Object.keys() types refinement, and Object.entries() types bugfix. GitHub.
TypeScript Documentation contributors. (2023, May 1). Type Compatibility. TypeScript: Documentation.

The AHA principle: Avoid hasty abstractions

Vladimír Zdražil — Sat, 01 Apr 2023 11:33:28 +0000

TLDR

AHA (Avoid Hasty Abstractions) principle advises preferring duplication over the wrong abstraction, optimizing for change first, and waiting for necessary abstractions to emerge. Benefits are easier maintenance and flexibility. Be careful about excessive avoidance of abstractions and potential refactoring/testing challenges.

Introduction

As a developer, you strive to write a clean and efficient code. One principle you likely follow is to avoid repetition and create abstractions for reusable code. However, there are times when duplicating code is the way to go and creating abstractions should wait.

The AHA principle

The AHA (Avoid Hasty Abstractions) principle advises you against creating unnecessary or premature abstractions that would otherwise increase code complexity and make maintenance more difficult in the long run. Instead, duplicate the code and hold off on refactoring until a clear and useful abstraction emerges.

You can summarize the AHA principle in 2 points:

Prefer duplication over the wrong abstraction.
Optimize for change first.

Kent C. Dodds described the AHA principle in his blog post AHA Programming. It’s based on Sandi Metz’s “Prefer duplication over the wrong abstraction”.

Benefits of AHA principle

Maintainability
- Without unnecessary abstractions, it’s easier to maintain and modify your code in the long run.
- Code is easier to read and understand, as it avoids unnecessary complexity.
Flexibility
- By optimizing for change first, you create code that is more adaptable to future changes and requirements.

Challenges of AHA principle

Excessive avoidance of abstractions
- Excessive avoidance of abstractions or delaying them for too long can backfire, resulting in a code that is difficult to maintain, defeating the very purpose of the AHA principle.
Refactoring and testing
- It may require more refactoring and testing when you eventually decide to abstract your code.

Reliance on developer judgment and experience

Q: Doesn’t the AHA principle rely too much on subjective judgment of developers to determine when and how to abstract their code?

A: Yes it does. Same as every other related principle. There’s no silver bullet and there’s no principle you can follow blindly. Think of it more like a guideline.

What about DRY and WET?

AHA suggests that both WET (Write Everything Twice) and DRY (Don’t Repeat Yourself) approaches can result in a software that is inflexible and difficult to maintain. Instead of starting with an abstraction (DRY) or abstracting after a certain number of duplications (WET), the AHA proposes to wait with the abstraction until you feel like you know the use cases for that duplicate code. At that point, you’ll have a clearer understanding of how the abstraction should function.

Conclusion

I can relate to the desire to create reusable code and avoid repetition. But sometimes duplication is the way to go, and that’s where the AHA principle comes in. It emphasizes the importance of carefully considering when and how to create abstractions, rather than automatically abstracting your code.

By avoiding premature abstractions, you create code that is easier to maintain and modify in the long run.

So, next time you face a coding challenge, don’t be afraid to duplicate your code if it makes sense. By doing so, you may actually be making your code easier to work with.

C. Dodds, K. (2020, June 22). AHA Programming. Kent C. Dodds.
Alternatives. In Don’t repeat yourself. (2023). In Wikipedia.
Metz, S. (2016, January 20). The Wrong Abstraction. Sandi Metz.

Links from the past few weeks (Nov 30, 2022)

Vladimír Zdražil — Wed, 30 Nov 2022 20:28:00 +0000

List of links, articles, and other resources you might find interesting from the past few weeks.

Markdown

Don’t complicate Markdown, use Markdown and HTML together

John Gruber and Aaron Swartz intended Markdown to be used for prose and for it to be readable with no further processing. When Markdown’s syntax is insufficient for what you need to do, you can use regular inline and block-level HTML elements.

There are Markdown flavors which see Markdown as too simplistic, and they extend its syntax. But in my opinion, that is a mistake. Let’s keep Markdown simple and use HTML for the more complex stuff.

This is also addressed in the official Markdown documentation:

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

Markdown: Syntax, HTML

So, don’t complicate Markdown. Just use Markdown and HTML together. Or maybe consider if Markdown is even what you want. You might be better off with regular HTML.

Is HTML a humane markup language? (2008)

What about HTML? Isn’t writing it easy enough? Do we even need Markdown?

Article Is HTML a humane markup language? (2008) by Jeff Atwood tries to dig deeper into these questions. I like how it raises the question that maybe HTML itself is already simple enough when programmers are the intended users. The most interesting tidbit:

But in general, I’d much rather rely on a subset of trusty old HTML than expend brain cells trying to remember the fake-HTML way to make something bold, or create a hyperlink. HTML isn’t perfect, but it’s an eminently reasonable humane markup language.

Is HTML a humane markup language? by Jeff Atwood

In the end, I’m still a fan of how Markdown does it. It simplifies the syntax for writing prose, but it doesn’t try to replace HTML and offers a simple way to use HTML for the more advanced stuff.

HTML and CSS

Accessibility insights

Trying to make your website more accessible? Microsoft has a free browser extension Accessibility Insights to help you with that.

W3C Core Styles

By default, HTML documents don’t look good because the default browser styles have some poor defaults. If you’d rather not bother with styling HTML documents yourself, you might want to try W3C Core Styles.

They offer several themes which you can just use by linking them from the head of your documents. Some of them look pretty outdated, but some of them still look good.

Accessible inline list with bullets between items

I’ve been looking for a way to create an accessible inline list with bullets between items, such as this: item 1 • item 2 • item 3. There are numerous solutions how to do this, but most of them don’t have good accessibility. The best solution I’ve found: Accessible inline list with bullets between items. It has some gotchas, all is described in the article.

Good taste

Linus Torvalds on good taste

In the interview Linus Torvalds on Linux, Git, and the future of open-source, Linus Torvalds touched upon something he describes as “good taste”:

But there is that occasional “inspiration” part, that “good taste” thing that is about more than just solving some problem — solving it cleanly and nicely and yes, even beautifully.

An interview with Linus Torvalds: Linux and Git — Part 1

I never thought this way about why some people solve programming problems more elegantly than others. In this interview, Linus Torvalds gives an interesting take on it.

Ira Glass on the creative process and a good taste

Ira Glass, host of the radio program This American Life, talks about the creative process and a good taste:

Play Ira Glass on good taste

But it’s like there’s a gap, that for the first couple years that you’re making stuff, what you’re making isn’t so good. … But your taste … is still killer, and your taste is good enough that you can tell that what you’re making is kind of a disappointment to you. … And the most important possible thing you can do is do a lot of work — do a huge volume of work.

Ira Glass on good taste

Internet

Don’t use services that hate the Internet

Weird things happening at Twitter, so you might be seeking some alternative. It’s critical to remember that you should try to avoid services that hate the Internet.

Programming

Just for fun. No, really.

If you ever make something just for fun and someone starts criticizing what you did, just remember the site Just for fun. No, really.

Because every so often you do something really just for fun. There’s no purpose, it’s not supposed to be better than something else, it might be even completely useless. It’s made just for fun.

Finding your favorite programming font

Find your favorite programming font by playing the coding font tournament.

Don’t rewrite project from scratch

Joel Spolsky has a pretty hard stance on rewriting large codebase from scratch: Don’t do it. It’s a waste of time and money, and you might even end up with something that’s worse than what you had before. It’s better to improve upon what you already have.

It’s important to remember that when you start from scratch there is absolutely no reason to believe that you are going to do a better job than you did the first time. First, you probably don’t even have the same programming team that worked on version one, so you don’t actually have “more experience”. You’re just going to make most of the old mistakes again, and introduce some new problems that weren’t in the original version.

Things you should never do, part I

Git tips and tricks

Vladimír Zdražil — Sat, 05 Nov 2022 05:53:47 +0000

Updates

2022-11-13: Added git repl section.
2023-05-07: This article has been split into multiple posts for easier reading and updating. Check out TIL Git for the latest tips.

A collection of Git tips and tricks you might not know.

Find the most frequently changed files

You can find the most frequently changed files in the repository with this command:

git log --pretty=format: --name-only <path> | sort | uniq -c | sort -rn | head -10
git log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -10
git log --pretty=format: --name-only packages/news | sort | uniq -c | sort -rn | head -10

The path limits the search to a specific directory, but you can omit it to search the whole repository.

You can use this list to decide which files to refactor first. For example, imagine you want to move a project from JavaScript to TypeScript. You can find the most changed files and start with them.

Or imagine you encounter a new codebase. Finding the most frequently changed files can help you figure out, what to focus on first.

Find the most recent branches

The following command will show you the branches sorted by the date of the last commit.

git config --global alias.recent "!git for-each-ref refs/heads --sort committerdate --format='%(HEAD) %(refname:short)'"
git recent

I sometimes forget the name of the branch I want to switch to, and this command makes finding it easy. But instead of git recent I aliased it to git brt, because it’s faster to type.

Reuse recorded resolution of conflicted merges

Git rerere can automatically resolve merge conflicts you resolved before, but you need to enable it first:

git config --global rerere.enabled true

More info in Git rerere.

Avoid unnecessary merge commits on pull

When you pull a branch, Git will by default create a merge commit. If you don’t want to have a merge commit, you can use the following setting to rebase the local commits instead:

git config --global pull.rebase true

As nobody knows your commits yet, nobody will get confused when you rebase them, and it keeps the history clean.

More info in Git config pull.rebase documentation.

Setup Git SSH signing

In version 2.34, Git introduced SSH signing. Git supported GPG signing for a long time, but I found it cumbersome. With SSH signing, you can use your already configured SSH key.

See how to set up Git SSH signing locally and on GitHub.

Import configs

You can include other configs in your .gitconfig file.

git config --global --add include.path '~/.git-config-work'

More info at Git config includes documentation.

Use git bisect to find buggy commits

If you have a bug in your code, and you want to find out which commit introduced it, you can use git bisect. With it, you will use binary search which is much faster than going through all the commits in a sequence.

git bisect start HEAD abc123 # HEAD is the buggy commit, abc123 is the good commit without a bug. It can be anywhere from the past.
git bisect bad # if Git switched to a commit which is bad/has a bug
git bisect good # if commit is good
git bisect reset # to abort

More info at The git’s guide to git: Bisect.

Auto setup remote on push

Git version 2.37 introduced a new config option: push.autoSetupRemote. You can use it to automatically set up a remote when you push. Which means you don’t need git push --set-upstream origin my-work or git push -u origin my-work anymore.

git config --global push.autoSetupRemote true

More info at Git config push.autoSetupRemote.

Git REPL

Tired of typing git when you run git commands? You can install git-extras and use its git repl to run multiple commands in a row.

git repl
status
add .
commit -m "Add feed"
push
exit

Links from the past few weeks (Oct 30, 2022)

Vladimír Zdražil — Sun, 30 Oct 2022 21:02:17 +0000

List of links, articles, and other resources you might find interesting from the past few weeks.

JavaScript

ECMAScript proposal: Decorators

JavaScript will soon have a new feature: decorators. The committee moved the proposal to stage 3.

The proposal defines decorators as functions called on classes, class elements, or other JavaScript syntax forms during definition. … Decorators let you metaprogram and add functionality to a value, without fundamentally changing its external behavior. Decorators for ES6 classes

What does it mean?

One example that made it much clearer for me was the one for class methods:

function logged(value, { kind, name }) {
  if (kind === "method") {
    return function (...args) {
      console.log(`starting ${name} with arguments ${args.join(", ")}`);
      const ret = value.call(this, ...args);
      console.log(`ending ${name}`);
      return ret;
    };
  }
}

class C {
  @logged
  m(arg) {}
}

new C().m(1);
// starting m with arguments 1
// ending m

This example roughly “desugars“ to:

class C {
  m(arg) {}
}

C.prototype.m =
  logged(C.prototype.m, {
    kind: "method",
    name: "m",
    static: false,
    private: false,
  }) ?? C.prototype.m;

Decorators for ES6 classes

ECMAScript proposal: Type annotations

Likewise, somebody prepared an interesting proposal for type annotations.

If realized, you could run programs written in TypeScript, Flow, and other static typing supersets of JavaScript with no need for transpilation. ECMAScript proposal: Type annotations

HTML

Description list versus unordered list with headings

Turns out, HTML supports description lists (otherwise called definition lists), and you should sometimes use them instead of unordered lists. They’re more suitable for things like listing post titles and their descriptions.

For example, you shouldn’t write this:

<h2>Posts</h2>
<ul>
  <li>
    <h3><a href="/posts/article-1/">Article 1</a></h3>
    <p>This summarizes article 1.</p>
  </li>
  <li>
    <h3><a href="/posts/article-2/">Article 2</a></h3>
    <p>This summarizes article 2.</p>
  </li>
</ul>

Instead, do this:

<h2>Posts</h2>
<dl>
  <dt><a href="/posts/article-1/">Article 1</a></dt>
  <dd>This summarizes article 1.</dd>
  <dt><a href="/posts/article-2/">Article 2</a></dt>
  <dd>This summarizes article 2.</dd>
</dl>

To understand why:

WHATWG or W3C?

When you search through HTML specifications, you might stumble upon two organizations: WHATWG and W3C.

Which one should you listen to?

WHATWG. WHATWG describes the browser implementation. W3C was more theoretical.

Furthermore, W3C and WHATWG signed an agreement to work together on a single version of HTML and DOM, agreeing that WHATWG will maintain the HTML and DOM Living Standards.

David Baron from Mozilla also says to prefer WHATWG:

When the W3C’s and WHATWG’s HTML specifications differ, we tend to follow the WHATWG one.

Before the srcset, there was a dynamic image resizing

You can serve responsive images using the srcset attribute. But what were people doing before?

You can read up on two solutions I’ve found:

CSS

What CSS units to prefer

It depends on what you want to do. See an excellent summary from Reddit user Tontonsb.

Furthermore, to go into more detail explaining why you shouldn’t settle with px unit, check out The surprising truth about pixels and accessibility.

CSS hyphenation

Did you know that websites can use hyphens? Find out more in All you need to know about hyphenation in CSS.

System font stack

You don’t always have to bother with loading custom fonts. A lot of people find regular system fonts great, and the text will still look beautiful.

For instance, see a perfect list of system fonts: System font stack.

Empathetic animations

Don’t do animations because you can. Use them to help the users understand what’s going on. More details in Empathetic animations.

Security

Make sure you send correct security headers

A lot of websites have improperly set security headers, or they didn’t set them at all. Test your site with observatory.mozilla.org to find the possible deficiencies. Another excellent alternative is securityheaders.com.

Fuzzy search through files in Visual Studio Code

Vladimír Zdražil — Tue, 19 Apr 2022 05:02:12 +0000

Visual Studio Code already supports searching across all the project files. But let’s make searching inside them even more ergonomic and easier to use. We’ll do it by taking an inspiration in the behavior of the command :RG from Vim plugin junegunn/fzf.vim.

The goal

Check out the Find in files in Visual Studio Code:

As an alternative, we’ll create a custom shell command rgf for fuzzy searching. After we select the result, command rgf will open the file in Visual Studio Code on the correct line. Then we’ll simplify running rgf from Visual Studio Code. We’ll build this new, alternative, flow:

Fuzzy searching in Visual Studio Code

Prerequisites

First, make sure you have these installed and set up so all works as expected:

Unix system, tested on macOS.
fzf >= 0.30.0
ripgrep >= 13.0.0
bat >= 0.20.0
Visual Studio Code >= 1.66.2
Extension Command Runner
You can open Visual Studio Code from the command line with the command code.
Bash >= 5.1.16

Recommended settings for fzf

Now, save this shell environment variable. Probably to $HOME/.bashrc, but it depends on your shell and your setup:

export FZF_DEFAULT_OPTS="--history=$HOME/.fzf-history"

This setting lets fzf load search history from the specified file and update the file on completion. You can then use Ctrl+N and Ctrl+P to go back and forward through search history and Ctrl+H and Ctrl+J or arrow keys ↑ and ↓ to select the next and previous result.

Install the script for fuzzy searching

Similarly, save the following script to your $PATH and make it executable, so you can run it in your shell:

#!/usr/bin/env bash

##
# Interactive search.
#
[[ -n $1 ]] && cd "$1" # go to provided folder or noop

export FZF_DEFAULT_COMMAND="rg --column --line-number --no-heading --color=always -- ''"
selected=$(
  fzf \
    --ansi \
    --delimiter : \
    --bind "f12:execute-silent:(code -g $PWD/{1..3})" \
    --preview-window 'up,60%,border-bottom,+{2}+3/3,~3' \
    --preview 'bat -f --highlight-line={2} {1}' | cut -d":" -f1,2,3
)

[[ -n $selected ]] && code -g "$PWD"/"$selected"

For example, on macOS, you can copy the script, then run this in your terminal:

pbpaste > ~/bin/rgf # ~/bin is in my $PATH
chmod +x ~/bin/rgf

Having done all this, you can now use rgf to fuzzy search in your shell. Try it!

What does the script do

The script combines fzf, rg, bat, and code to fuzzy search through your code and to open the result in Visual Studio Code. I based it on Using fzf as interactive ripgrep launcher.

Compared to the original, the script behaves like the :RG command in junegunn/fzf.vim. It uses fzf fuzzy searching right away, and it doesn’t pre-filter the results with ripgrep. The script uses ripgrep to list the lines in the project, with path, filename, and line number.

Install fuzzy search command to Visual Studio Code

Next in order, simplify running rgf from Visual Studio Code.

Add this to your Visual Studio Code settings.json:

{
  "command-runner.commands": {
    "rgf": "rgf; exit"
  }
}

After doing this, you can:

Press Cmd+Shift+P.
Select Run Command.
Select rgf.
Now you can fuzzy-search. Press Enter to open the search result and close the window. Or press F12. This won’t close the window, making it possible to continue with your search uninterrupted.

Add fuzzy search shortcut

Add this to your Visual Studio Code keybindings.json:

{
  "args": { "command": "rgf" },
  "command": "command-runner.run",
  "key": "cmd+k ."
}

New workflow

After doing this, you can:

Press Cmd+K and then . to start fuzzy searching.
Press Enter to open the search result and close the search window. Or press F12. This won’t close the window. Instead, it will open the search result, and you can continue with your search. This way, you can open multiple files without canceling the search.

Fuzzy searching in Visual Studio Code

How does this differ from the default

Fuzzy search

I want to avoid writing complicated regular expressions. I prefer not to write out the full names. If I’m looking for the function getSelectedAddressFormValues, I should be able to find it with the search term getseladd.

In comparison with Find in files, you don’t need regex.

One field, nothing more

With Find in files, you have several input fields and extra toggles which you need to keep checking and toggling either with a mouse or complicated shortcuts.

Instead, I want to have one input field where the search term affects almost everything. See how fzf does it. Do you want to use the exact match? 'wild Do you want to use an inverse match? !wild

Everything is part of the search term.

Limiting the files included in the search is easier

With Find in files, you can limit the files included in your search in at least two ways, but I find neither of them ergonomic enough:

Write out the exact path of the folder, for example, ./packages/my-package/web-app, to a separate field.
Select a folder in the folder list and then run the Find in folder command.

Why do you need to write out the whole path? You can use glob syntax. But you still have to figure out where to put them.

By comparison, what if you could enter the folder/file name right inside the same input field as the search term and use fuzzy matching? You’d find a lot of things faster.

Example

Take the case of finding the word wild inside the folder web-app. The folder web-app is located in ./packages/web-app.

I’d like to use this search term:

web-app wild

Or even this should work:

weba wild # fuzzy matching

Complete search history

Lastly, with Find in files, you can go through previous searches but Visual Studio Code doesn’t remember the switches and files to include field. I’d prefer to have access to the complete search history, with the toggles and other fields as part of it.