9 articles tagged “programming” — software, engineering, and related writing by idmontie.

Programming blog posts - idmontie's Portfolio

As I was reading through the Petar Maymounkov and David Mazières paper ["Kademlia: A Peer-to-peer Information System Based on the XOR Metric"](https://pdos.csail.mit.edu/~petar/papers/maymounkov-kademlia-lncs.pdf), I was interested in the application of this XOR metric on work I had previously done on [clustering embeddings](/blog/post/2023-07-01-fast-embedding-lookingup). When implementing the Infer API for Clarity Hub, we focused on using the distance between vectors as a way to cluster utterances together into a topic. We did this via [Euclidean distance](https://en.wikipedia.org/wiki/Euclidean_distance) between vectors, which we had to compare against all other vectors within the space.



$$
d(p,q)=\sqrt{\sum_{i=1}^{n}(p_i-q_i)^2}
$$

Since we were comparing the magnitude of the distance, we removed the square root from the calculation:

$$
(d(p,q))^2=\sum_{i=1}^{n}(p_i-q_i)^2
$$

Sorting by $d^2$ gives the same ordering as sorting by $d$.

Computing a Euclidean distance between all the pairs of embeddings is rather computationally expensive, even if we remove the square root from the operation. Is there a way we could speed this up?

## The XOR Distance

In the Kademlia paper, the XOR distance is used to compare two bit strings, $p$ and $q$.

$$
X(p,q)=p\oplus q
$$

The result of this XOR is interpretted by Kademlia as an integer. Identical bit-strings have a value of $0$, while differences in increasingly significant bits produce increasingly larger values. For example, here is the result of two identical bit-strings:

| | Bit string |
|---|---|
| $p$ | `10110110` |
| $q$ | `10110110` |
| $p \oplus q$ | `00000000` |
| XOR distance | `0` |

Likewise, if $p$ and $q$ were compliments of each other, every bit in their XOR result would be $1$. For an 8-bit value, that gives an integer value of the maximum possible size of $255$:

| | Bit string |
|---|---|
| $p$ | `10110110` |
| $q$ | `01001001` |
| $p\oplus q$ | `11111111` |
| XOR distance | $255$ |


The XOR distance has some interesting properties that are similar to the Euclidean metric:

- The order of $p$ and $q$ does not matter - XOR distance is symmetric.
- The output of $p$ XOR $q$ is always the same - XOR distance is deterministic.
- It satisfies the triangly inequality.

These properties allow XOR distance to define a consistent notion of closeness that is used in Kademlia's identifier space. For our purposes, there is one property the XOR Distance gives that is useful in the Kademlia paper, but is counter to our purposes for vector similarity. Higher-order bits in the bit-string (those farther "left") can radically change the XOR distance. This behavior is useful in Kademlia because it organizes nodes according to common identifier prefixes, but is undesirable in our case where every dimension of the embedding vector should contribute equally.

Instead of looking at the result of the XOR as an integer, we can look at the number of 1 bits in the result – called the "population count" or $popcount$.

## The Hamming Distance

The Hamming distance between two bit-strings is the number of bits that differ, and we use the following definition:

$$
X(p,q)=p\oplus q
$$

and

$$
d_H(p,q)=\frac{\operatorname{popcount}(X(p,q))}{n}
$$

where `n` is the number of bits. `popcount` is the “population count” of how many 1s are in the bit string. By dividing by the number of bits, we normalize the Hamming Distance.

For example, if we have two bit-strings p and q that are the same, then the Hamming distance will be 0 between them:

| | Bit string |
|---|---|
| $p$ | `10110110` |
| $q$ | `10110110` |
| $p \oplus q$ | `00000000` |
| popcount | `0` |
| normalized Hamming distance | $0/8=0$ |

That normalized distance ranges from 0 to 1. And if we have bit strings that are compliments, then the normalized Hamming distance will be 1:


| | Bit string |
|---|---|
| $p$ | `10110110` |
| $q$ | `01001001` |
| $p \oplus q$ | `11111111` |
| popcount | `8` |
| normalized Hamming distance | $8/8=1$ |


We only have one more hurdle to computing the Hamming distance between embeddings.

## Converting Embeddings to Bit Strings

Embeddings are vectors of floats, and can be fairly high dimensionality. We need a deterministic, yet fast way to convert an embedding from a vector of floats into bit-strings that we can XOR. Naively XOR’ing the floats would not be useful since similar float values can have a fairly large distance between their IEEE-754 representation as bits:

```jsx
0.73 → 00111111001110101110000101001000
0.72 → 00111111001110000101000111101100
```

What we can do instead is apply a technique called a SimHash. For an embedding $x$ of dimension $d$, we pre-compute a matrix $R$ with rows $k$ by $d$ columns that are filled with random values. Each row of this matrix is called a "random-hyperplane" and ultimately produces on bit of our binary representation.

Then we apply the following transformation:

$$
b_i =
\begin{cases}
1 & r_i \cdot x \ge 0 \\
0 & r_i \cdot x < 0
\end{cases}
$$

I won’t go into the specifics of why the SimHash works, but there is an important property of random-hyperplane hashing worth noting. If two vectors $p$ and $q$ have an angle $\theta$ between them, the probability that the transform gives them different bits is $\theta$ over $\pi$. Generally this transformation preserves cosine similarity between all the vectors.

This does not exactly preserve the euclidean distances we originally looked at. Instead it produces a probabilistic approximation. In the case of Universal Sentence Encoder embeddings, they are approximately normalized. And for unit-normalized vectors, the Euclidean distance is directly related to the cosine similartity.

This means that Euclidean distance, cosine similarity, and angular distance produce the same ordering for unit vectors. Our transformation from the Universal Sentence Encoder embedding into a bit-string representation will lose some of this ordering information, but generally will produce similar ranking for our next steps.

The Universal Sentence Encoder produces 512-dimensional embeddings. If we generate a random matrix of size 256 by 512, applying the transformation gives us a 256-bit binary represenation of each embedding. We apply the same transformation to all our embeddings.

For example, let’s work with an embedding of dimension 3:

$$
x=
\begin{bmatrix}
0.8\\
-0.2\\
0.5
\end{bmatrix}
$$

And we choose a random projection matrix whose four rows define four hyperplanes:

$$
R=
\begin{bmatrix}
1 & -1 & 1\\
-1 & 1 & 1\\
1 & 1 & -1\\
-1 & -1 & 1
\end{bmatrix}
$$

Multiplying the projection matrix by our embedding gives:

$$
Rx=
\begin{bmatrix}
1.5\\
-0.5\\
0.1\\
-0.1
\end{bmatrix}
$$

And using our simple transformation, we get the following table of bits from the projection:

| Projection | Value | Bit |
|---|---:|---:|
| $r_1\cdot x$ | 1.5 | 1 |
| $r_2\cdot x$ | -0.5 | 0 |
| $r_3\cdot x$ | 0.1 | 1 |
| $r_4\cdot x$ | -0.1 | 0 |

Giving the final bit-string of `1010`.

## What would we gain?

By turning the embedding from a vector of floats into a bit-string, we can substantially reduce the size. Universal Sentence Encoder produces a 512-dimensional embedding using 32-bit floating-point values. The original embedding therefor requires 512 x 32 = 16,384 bits. After the transformation, we require only 256-bits. That’s a substantial memory savings, especially given that we need to typically load a large chunk of these embeddings into memory to do clustering calculations.

As for computational performance, the transformation from floating point numbers into the bit-string is not free. We need to perform 512 x 256 operations – about 131000 operations – to transform a new utterance.

If there are N existing embeddings, inserting a new embedding requires roughly:

$$
\text{Euclidean: } O(512N)
$$

For the binary representation, let $C$ be the one-time cost of creating the projection. A 256-bit value can be represented as four 64-bit machine words, giving:

$$
\text{Binary: } C + O(4N)
$$

As N grows, the fixed projection cost becomes increasingly small relative to the cost of comparing all the embeddings. Each Euclidean comparison checks 512 floating-point dimensions, while the normalize Hamming distance only needs to check 4 64-bit words. This article is all a hypothetical in terms of the savings, so I would like to run a real experiment of this to see how much of a real-world speedup would be seen.

The final trade-off is that the 256-bit representation is also an approximation of the original embedding geometry. For clustering, a real-world experiment would need to be run in order to check for the accuracy of such a transformation, especially near the boundaries of clusters.

Lastly, the work noted here is not novel, and there must be research published that touches on these types of transformations and how much performance versus accuracy is produced.

Other references

- [XOR Distance in Kademlia](https://rfong.github.io/rflog/2022/04/09/xor-distance-kademlia/)
- [Bitwise and Otherwise: Understanding XOR Distance](https://dev.to/lovestaco/bitwise-and-otherwise-understanding-xor-distance-1kh8)
- [Semantic Similarity with TF Hub Universal Encoder](https://www.tensorflow.org/hub/tutorials/semantic_similarity_with_tf_hub_universal_encoder)

Speeding Up Embedding Comparisons

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    a: "a",
    code: "code",
    h3: "h3",
    li: "li",
    ol: "ol",
    p: "p",
    pre: "pre",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsxs(_components.p, {
      children: ["We all end up doing it: ", _jsx(_components.code, {
        children: "// TODO implement this function"
      }), ", or ", _jsx(_components.code, {
        children: "// TODO handle this edge case"
      }), ". Often as we write code, we use ", _jsx(_components.code, {
        children: "TODO"
      }), "s to track ephemeral work, and typically clean them up as we go along. But sometimes we keep that ", _jsx(_components.code, {
        children: "TODO"
      }), " around, and it ends up in main. Then what?"]
    }), "\n", _jsxs(_components.p, {
      children: ["Sophie Alpert, in “TODOs aren’t for doing”, argues that the comments themselves are valuable since they may reveal the original authors’ intentions – or, more importantly, their lack of intention for handling a specific edge case. ", _jsx(_components.code, {
        children: "TODO"
      }), " comments often do a good job of saying “why” code is the way it is, rather than “how” something works the way it does."]
    }), "\n", _jsxs(_components.p, {
      children: ["The blog post goes on to say that requiring ", _jsx(_components.code, {
        children: "TODO"
      }), "s to have a ticket associated with them is something we should avoid. This is where our opinions diverge. In places I have worked, I have created custom lint rules that require a ", _jsx(_components.code, {
        children: "TODO"
      }), " to have a corresponding ticket written as part of their definition, something like ", _jsx(_components.code, {
        children: "// TODO(xyz-123): description"
      }), " . The intention here is twofold:"]
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "By making engineers write a ticket, they often think about whether writing a ticket is worth the time, rather than just implementing the functionality."
      }), "\n", _jsx(_components.li, {
        children: "It helps deprioritize work that may not be necessary."
      }), "\n"]
    }), "\n", _jsxs(_components.p, {
      children: ["For example, I would often see code around error handling littered with ", _jsx(_components.code, {
        children: "TODO"
      }), "s; ", _jsx(_components.code, {
        children: "// TODO implement a better fallback when X system fails"
      }), " or ", _jsx(_components.code, {
        children: "// TODO log the issue in our monitoring system"
      }), ". With the rule enabled, that all but disappeared. Engineers simply started adding logging rather than creating a follow-up ticket."]
    }), "\n", _jsxs(_components.p, {
      children: ["Other times, a ", _jsx(_components.code, {
        children: "TODO"
      }), " turns into a task that we follow up later in a refinement. Engineers then get to discuss with product whether something is even worth doing."]
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-tsx",
        children: "// TODO(XYZ-123): use new API to get the latest data, rather then the deprecated API\n"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["The team can now set aside time in their sprint or an upcoming sprint to tackle the tricky issue that the ", _jsx(_components.code, {
        children: "TODO"
      }), " marked. Or in the case where product decides it is not worth doing, the ", _jsx(_components.code, {
        children: "TODO"
      }), " can become documentation like Sophie Alpert mentioned"]
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-tsx",
        children: "// XYZ-123: decision was made to continue to use the old API for the foreseeable future\n"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["In this way, comments are linked with the work and decisions that were made, rather than one-off ", _jsx(_components.code, {
        children: "TODOs"
      }), ". Any amount of documentation is better than no documentation, so if you are using TODO comments as a way of documenting pending work, that is preferable to not marking work at all. In that way, a good ", _jsx(_components.code, {
        children: "TODO"
      }), " is linked with pending work. It marks the intention of what code was missing when writing the original implementation."]
    }), "\n", _jsx(_components.h3, {
      children: "References"
    }), "\n", _jsxs(_components.p, {
      children: [_jsx(_components.a, {
        href: "sophiebits.com/2025/07/21/todos-arent-for-doing",
        children: "TODOs aren't for doing"
      }), " - Big shout out to Sophie Bits, go check it out."]
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>We all end up doing it: <code>// TODO implement this function</code>, or <code>// TODO handle this edge case</code>. Often as we write code, we use <code>TODO</code>s to track ephemeral work, and typically clean them up as we go along. But sometimes we keep that <code>TODO</code> around, and it ends up in main. Then what?</p>
<p>Sophie Alpert, in “TODOs aren’t for doing”, argues that the comments themselves are valuable since they may reveal the original authors’ intentions – or, more importantly, their lack of intention for handling a specific edge case. <code>TODO</code> comments often do a good job of saying “why” code is the way it is, rather than “how” something works the way it does.</p>
<p>The blog post goes on to say that requiring <code>TODO</code>s to have a ticket associated with them is something we should avoid. This is where our opinions diverge. In places I have worked, I have created custom lint rules that require a <code>TODO</code> to have a corresponding ticket written as part of their definition, something like <code>// TODO(xyz-123): description</code> . The intention here is twofold:</p>
<ol>
<li>By making engineers write a ticket, they often think about whether writing a ticket is worth the time, rather than just implementing the functionality.</li>
<li>It helps deprioritize work that may not be necessary.</li>
</ol>
<p>For example, I would often see code around error handling littered with <code>TODO</code>s; <code>// TODO implement a better fallback when X system fails</code> or <code>// TODO log the issue in our monitoring system</code>. With the rule enabled, that all but disappeared. Engineers simply started adding logging rather than creating a follow-up ticket.</p>
<p>Other times, a <code>TODO</code> turns into a task that we follow up later in a refinement. Engineers then get to discuss with product whether something is even worth doing.</p>
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-tsx">// TODO(XYZ-123): use new API to get the latest data, rather then the deprecated API
</code></pre></div>
<p>The team can now set aside time in their sprint or an upcoming sprint to tackle the tricky issue that the <code>TODO</code> marked. Or in the case where product decides it is not worth doing, the <code>TODO</code> can become documentation like Sophie Alpert mentioned</p>
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-tsx">// XYZ-123: decision was made to continue to use the old API for the foreseeable future
</code></pre></div>
<p>In this way, comments are linked with the work and decisions that were made, rather than one-off <code>TODOs</code>. Any amount of documentation is better than no documentation, so if you are using TODO comments as a way of documenting pending work, that is preferable to not marking work at all. In that way, a good <code>TODO</code> is linked with pending work. It marks the intention of what code was missing when writing the original implementation.</p>
<h3>References</h3>
<p><a href="sophiebits.com/2025/07/21/todos-arent-for-doing">TODOs aren&#x27;t for doing</a> - Big shout out to Sophie Bits, go check it out.</p>


We all end up doing it: `// TODO implement this function`, or `// TODO handle this edge case`. Often as we write code, we use `TODO`s to track ephemeral work, and typically clean them up as we go along. But sometimes we keep that `TODO` around, and it ends up in main. Then what?

Sophie Alpert, in “TODOs aren’t for doing”, argues that the comments themselves are valuable since they may reveal the original authors’ intentions – or, more importantly, their lack of intention for handling a specific edge case. `TODO` comments often do a good job of saying “why” code is the way it is, rather than “how” something works the way it does.

The blog post goes on to say that requiring `TODO`s to have a ticket associated with them is something we should avoid. This is where our opinions diverge. In places I have worked, I have created custom lint rules that require a `TODO` to have a corresponding ticket written as part of their definition, something like `// TODO(xyz-123): description` . The intention here is twofold:

1. By making engineers write a ticket, they often think about whether writing a ticket is worth the time, rather than just implementing the functionality.
2. It helps deprioritize work that may not be necessary.

For example, I would often see code around error handling littered with `TODO`s; `// TODO implement a better fallback when X system fails` or `// TODO log the issue in our monitoring system`. With the rule enabled, that all but disappeared. Engineers simply started adding logging rather than creating a follow-up ticket.

Other times, a `TODO` turns into a task that we follow up later in a refinement. Engineers then get to discuss with product whether something is even worth doing.

```tsx
// TODO(XYZ-123): use new API to get the latest data, rather then the deprecated API
```

The team can now set aside time in their sprint or an upcoming sprint to tackle the tricky issue that the `TODO` marked. Or in the case where product decides it is not worth doing, the `TODO` can become documentation like Sophie Alpert mentioned

```tsx
// XYZ-123: decision was made to continue to use the old API for the foreseeable future
```

In this way, comments are linked with the work and decisions that were made, rather than one-off `TODOs`. Any amount of documentation is better than no documentation, so if you are using TODO comments as a way of documenting pending work, that is preferable to not marking work at all. In that way, a good `TODO` is linked with pending work. It marks the intention of what code was missing when writing the original implementation.

### References

[TODOs aren't for doing](sophiebits.com/2025/07/21/todos-arent-for-doing) - Big shout out to Sophie Bits, go check it out.

What Makes a Good TODO?

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    a: "a",
    code: "code",
    h2: "h2",
    h3: "h3",
    p: "p",
    pre: "pre",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsxs(_components.p, {
      children: ["I've discussed ", _jsx(_components.a, {
        href: "/blog/post/2023-08-14-partial-objects",
        children: "full and partial objects before on this blog"
      }), ", and in this article I'm going to investigate a common factory pattern\nin Typescript that can lead to type-holes.\nWhen writing tests or complex components, I'll often create prop factory utilities."]
    }), "\n", _jsx(_components.p, {
      children: "For tests, the goal is to create props with all the default values, except a few that may be\noveridden for a specific test case. The function signature typically looks like this:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-jsx",
        children: "function makeFoo(partial?: Partial<Foo>): Foo;\n"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["The expectation is that a software developer can call ", _jsx(_components.code, {
        children: "makeFoo"
      }), " and get a version of ", _jsx(_components.code, {
        children: "Foo"
      }), " that has all the defaults set to use in tests. Then, if the developer want to override a few fields to test an edge case, all they do is call ", _jsx(_components.code, {
        children: "makeFoo({ fieldA: 'special-case })"
      }), "."]
    }), "\n", _jsx(_components.p, {
      children: "I’ve seen developers try to implement this a few ways, each with its pros and cons."
    }), "\n", _jsx(_components.h3, {
      children: "Spreading"
    }), "\n", _jsx(_components.p, {
      children: "The easiest way to implement this function is to just provide defaults and spread the partial:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-jsx",
        children: "interface Foo {\n  fieldA: string;\n  fieldB?: string;\n  fieldC?: boolean | null;\n}\n\nfunction makeFoo(partial?: Partial<Foo>): Foo {\n  return {\n\t  fieldA: 'test',\n    fieldB: 'example',\n    fieldC: false,\n    ...partial\n  };\n}\n"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["Here, we create a ", _jsx(_components.code, {
        children: "Foo"
      }), "  mock with overrides for the defaults, which are provided by ", _jsx(_components.code, {
        children: "partial?: Partial<Foo>"
      }), " . However, even though ", _jsx(_components.code, {
        children: "fieldA"
      }), " is required, we can see a type-hole with the default Typescript compilation settings:"]
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-jsx",
        children: "const instance = makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });\nconsole.log(instance.fieldA);\n\n// No type error, but this blows up\nconsole.log(instance.fieldA.toLowerCase());\n"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["When we spread, ", _jsx(_components.code, {
        children: "undefined"
      }), " actually overrides the default! But why were we allowed to provide ", _jsx(_components.code, {
        children: "undefined"
      }), " in the first place?"]
    }), "\n", _jsxs(_components.p, {
      children: ["In Typescript, ", _jsx(_components.code, {
        children: "Partial<Foo>"
      }), "  keeps all the fields, but makes them optional. In the default compilation settings, an optional field can be set to ", _jsx(_components.code, {
        children: "undefined"
      }), "."]
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.a, {
        href: "https://www.typescriptlang.org/play/?#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkyDohbGMgtOjyXSToTA5TYDMQXamUx-oA9O-IAHJYYACeThQ0Cg6CguRk6jAyDAAAtgLQZNcAO6I9ROXCnc6Xa63e6PZ5FChdMDoAAy6GR0HEcDaDhCxyAA",
        children: "Typescript Playground Link"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["There is a Typescript compilation flag to throw a type-error and keep our sanity: ", _jsx(_components.code, {
        children: "exactOptionalPropertyTypes"
      }), ". Enabling this flag makes Typescript show an error for ", _jsx(_components.code, {
        children: "makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });"
      }), ". We can add the field to the call if it is set to a value."]
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.a, {
        href: "https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkuevFmyDbu-uHqRInZ6D7yDohbGMgtOjyXSToTA5TYDMQLpXChPUbjd6Ar4-P4AoFFChdMDoAAy6AA7tBxHA2g4Qk8gA",
        children: "Typescript Playground Link"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["But this causes another problem: it is perfectly valid to create an initial instance of ", _jsx(_components.code, {
        children: "Foo"
      }), " without fieldB being set (and its value being ", _jsx(_components.code, {
        children: "undefined"
      }), "). But now our ", _jsx(_components.code, {
        children: "makeFoo"
      }), " object doesn’t allow us to pass ", _jsx(_components.code, {
        children: "fieldB: undefined"
      }), " anymore. Only when the interface explicitly defines fieldB as optional AND undefined does it allow us to so."]
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.a, {
        href: "https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQTZAB9kAVxBkIREBDJsCRUmQDCfZACNMJCHBCjkIcSRJsAvrlwxJCMMHQGAtnADWEDOgAUABzhR7OBINAAV-QJIAHk8APgBKGk8cdigIMHEoAzwASCVOShoAckh6QoAadjyVLiKIAA84Jx9dcsqOFVUaeBJaCAqCAgA6Yb8A4CD2cwsrBEd6ZFB6fSRkAF5kF3dPL2x27hpJaVl5ZHM4tlmQWnRdQZJ0Ji9FsGWIQeVyCnOZuZu3+8ez1e73yFEGYHQABl0AB3aCqOC9Lxxc5AA",
        children: "Typescript Playground Link"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["Generally this pattern without the flag is fine for creating mock data, since any type-holes would only be scoped to tests and not real production code. But the question is: can we have ", _jsx(_components.code, {
        children: "makeFoo"
      }), " take a partial, return Foo without type-holes, and have allow ", _jsx(_components.code, {
        children: "undefined"
      }), " for partials?"]
    }), "\n", _jsx(_components.h2, {
      children: "Null-Coalescing Every Field"
    }), "\n", _jsx(_components.p, {
      children: "Another common implementation I have seen is to add nullish coalescing to every field:"
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-jsx",
        children: "interface Foo {\n  fieldA: string;\n  fieldB?: string;\n  fieldC?: boolean | null;\n}\n\nfunction makeFoo(partial?: Partial<Foo>): Foo {\n  return {\n\t  fieldA: partial?.fieldA ?? 'test',\n    fieldB: partial?.fieldB ?? 'example',\n    fieldC: partial?.fieldC ?? false,\n  };\n} \n"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["Let’s also turn off the ", _jsx(_components.code, {
        children: "exactOptionalPropertyTypes"
      }), " compilation flag for now."]
    }), "\n", _jsxs(_components.p, {
      children: ["We know every field will be set correctly, so there are no type-holes in ", _jsx(_components.code, {
        children: "Foo"
      }), ", however, we still have the problem where we cannot override a field to the ", _jsx(_components.code, {
        children: "unset"
      }), " value of ", _jsx(_components.code, {
        children: "undefined"
      }), " :"]
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.a, {
        href: "https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=false&ssl=13&ssc=2&pln=1&pc=1#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTILm7AHjwAdKmUyDw8yADkkPSlADTsKZxkXDSZfnkFXEUlpRAAHnAWTvLVtRxi4k2+2Z759eIdhB60EDUEOrr6COb0yKD0ikjIALzIVrb2DtgjaTRGZBBEIBBkVZcN1yC394-IOiFsGyC0dDyXIkdBMBw7MB7CDTMQUX64f6A4Gg8GQ6Gw7gIxGbIEw1EQgFQ4wwgoUXJgdAAGXQAHdoOI4IsHCEEUA",
        children: "Typescript Playground Link"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["Turning on the ", _jsx(_components.code, {
        children: "exactOptionalPropertyTypes"
      }), " also doesn’t save us here since we didn’t have a type-issue anyway, but more of a logic issue. ", _jsx(_components.code, {
        children: "makeFoo({ fieldB: undefined })"
      }), " will still set ", _jsx(_components.code, {
        children: "fieldB"
      }), " to ", _jsx(_components.code, {
        children: "example"
      }), "."]
    }), "\n", _jsx(_components.h2, {
      children: "Allowing bad inputs"
    }), "\n", _jsxs(_components.p, {
      children: ["This last approach takes the first and second approaches above and combines them using a ", _jsx(_components.code, {
        children: "pickOrDefault"
      }), " function. Here if any value is passed into the partial, we will return it, except when that value would be incorrect in the output type:"]
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "language-tsx",
        children: "function isValuePresent<T extends object>(obj: T, key: keyof T): boolean {\n    return key in obj;\n}\n\nfunction pickOrDefault<T extends object, K extends keyof T>(partial: T, key: K, fallbackValue: T[K]): T[K] {\n  if (key in partial) {\n    return partial[key];\n  }\n\n  return fallbackValue\n}\n\ninterface Foo {\n  fieldA: string;\n  fieldB?: string;\n  fieldC?: boolean | null;\n}\n\nfunction makeFoo(partial: Partial<Foo> = {}): Foo {\n  return {\n\t  fieldA: pickOrDefault(partial, 'fieldA', 'test') ?? 'test',\n    fieldB: pickOrDefault(partial, 'fieldB', 'example'),\n    fieldC: pickOrDefault(partial, 'fieldC', true),\n  };\n}\n\nconst instance = makeFoo({ fieldA: undefined, fieldB: undefined });\nconsole.log(instance.fieldA);\nconsole.log(instance.fieldB);\n\nconsole.log(instance.fieldA.toLowerCase());\n\n"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["For each field, we prefer the input partial, except here the type mismatch for ", _jsx(_components.code, {
        children: "fieldA"
      }), " forced us to add the default value twice, once if the partial didn’t have a value, and once if the partial had ", _jsx(_components.code, {
        children: "undefined"
      }), " which isn’t allows in the final version of ", _jsx(_components.code, {
        children: "type Foo"
      }), "."]
    }), "\n", _jsx(_components.p, {
      children: "While more verbose, this does eliminate the type holes the code!"
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>I&#x27;ve discussed <a href="/blog/post/2023-08-14-partial-objects">full and partial objects before on this blog</a>, and in this article I&#x27;m going to investigate a common factory pattern
in Typescript that can lead to type-holes.
When writing tests or complex components, I&#x27;ll often create prop factory utilities.</p>
<p>For tests, the goal is to create props with all the default values, except a few that may be
overidden for a specific test case. The function signature typically looks like this:</p>
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-jsx">function makeFoo(partial?: Partial&lt;Foo&gt;): Foo;
</code></pre></div>
<p>The expectation is that a software developer can call <code>makeFoo</code> and get a version of <code>Foo</code> that has all the defaults set to use in tests. Then, if the developer want to override a few fields to test an edge case, all they do is call <code>makeFoo({ fieldA: &#x27;special-case })</code>.</p>
<p>I’ve seen developers try to implement this a few ways, each with its pros and cons.</p>
<h3>Spreading</h3>
<p>The easiest way to implement this function is to just provide defaults and spread the partial:</p>
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-jsx">interface Foo {
  fieldA: string;
  fieldB?: string;
  fieldC?: boolean | null;
}

function makeFoo(partial?: Partial&lt;Foo&gt;): Foo {
  return {
	  fieldA: &#x27;test&#x27;,
    fieldB: &#x27;example&#x27;,
    fieldC: false,
    ...partial
  };
}
</code></pre></div>
<p>Here, we create a <code>Foo</code>  mock with overrides for the defaults, which are provided by <code>partial?: Partial&lt;Foo&gt;</code> . However, even though <code>fieldA</code> is required, we can see a type-hole with the default Typescript compilation settings:</p>
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-jsx">const instance = makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });
console.log(instance.fieldA);

// No type error, but this blows up
console.log(instance.fieldA.toLowerCase());
</code></pre></div>
<p>When we spread, <code>undefined</code> actually overrides the default! But why were we allowed to provide <code>undefined</code> in the first place?</p>
<p>In Typescript, <code>Partial&lt;Foo&gt;</code>  keeps all the fields, but makes them optional. In the default compilation settings, an optional field can be set to <code>undefined</code>.</p>
<p><a href="https://www.typescriptlang.org/play/?#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkyDohbGMgtOjyXSToTA5TYDMQXamUx-oA9O-IAHJYYACeThQ0Cg6CguRk6jAyDAAAtgLQZNcAO6I9ROXCnc6Xa63e6PZ5FChdMDoAAy6GR0HEcDaDhCxyAA">Typescript Playground Link</a></p>
<p>There is a Typescript compilation flag to throw a type-error and keep our sanity: <code>exactOptionalPropertyTypes</code>. Enabling this flag makes Typescript show an error for <code>makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });</code>. We can add the field to the call if it is set to a value.</p>
<p><a href="https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkuevFmyDbu-uHqRInZ6D7yDohbGMgtOjyXSToTA5TYDMQLpXChPUbjd6Ar4-P4AoFFChdMDoAAy6AA7tBxHA2g4Qk8gA">Typescript Playground Link</a></p>
<p>But this causes another problem: it is perfectly valid to create an initial instance of <code>Foo</code> without fieldB being set (and its value being <code>undefined</code>). But now our <code>makeFoo</code> object doesn’t allow us to pass <code>fieldB: undefined</code> anymore. Only when the interface explicitly defines fieldB as optional AND undefined does it allow us to so.</p>
<p><a href="https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQTZAB9kAVxBkIREBDJsCRUmQDCfZACNMJCHBCjkIcSRJsAvrlwxJCMMHQGAtnADWEDOgAUABzhR7OBINAAV-QJIAHk8APgBKGk8cdigIMHEoAzwASCVOShoAckh6QoAadjyVLiKIAA84Jx9dcsqOFVUaeBJaCAqCAgA6Yb8A4CD2cwsrBEd6ZFB6fSRkAF5kF3dPL2x27hpJaVl5ZHM4tlmQWnRdQZJ0Ji9FsGWIQeVyCnOZuZu3+8ez1e73yFEGYHQABl0AB3aCqOC9Lxxc5AA">Typescript Playground Link</a></p>
<p>Generally this pattern without the flag is fine for creating mock data, since any type-holes would only be scoped to tests and not real production code. But the question is: can we have <code>makeFoo</code> take a partial, return Foo without type-holes, and have allow <code>undefined</code> for partials?</p>
<h2>Null-Coalescing Every Field</h2>
<p>Another common implementation I have seen is to add nullish coalescing to every field:</p>
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-jsx">interface Foo {
  fieldA: string;
  fieldB?: string;
  fieldC?: boolean | null;
}

function makeFoo(partial?: Partial&lt;Foo&gt;): Foo {
  return {
	  fieldA: partial?.fieldA ?? &#x27;test&#x27;,
    fieldB: partial?.fieldB ?? &#x27;example&#x27;,
    fieldC: partial?.fieldC ?? false,
  };
} 
</code></pre></div>
<p>Let’s also turn off the <code>exactOptionalPropertyTypes</code> compilation flag for now.</p>
<p>We know every field will be set correctly, so there are no type-holes in <code>Foo</code>, however, we still have the problem where we cannot override a field to the <code>unset</code> value of <code>undefined</code> :</p>
<p><a href="https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=false&amp;ssl=13&amp;ssc=2&amp;pln=1&amp;pc=1#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTILm7AHjwAdKmUyDw8yADkkPSlADTsKZxkXDSZfnkFXEUlpRAAHnAWTvLVtRxi4k2+2Z759eIdhB60EDUEOrr6COb0yKD0ikjIALzIVrb2DtgjaTRGZBBEIBBkVZcN1yC394-IOiFsGyC0dDyXIkdBMBw7MB7CDTMQUX64f6A4Gg8GQ6Gw7gIxGbIEw1EQgFQ4wwgoUXJgdAAGXQAHdoOI4IsHCEEUA">Typescript Playground Link</a></p>
<p>Turning on the <code>exactOptionalPropertyTypes</code> also doesn’t save us here since we didn’t have a type-issue anyway, but more of a logic issue. <code>makeFoo({ fieldB: undefined })</code> will still set <code>fieldB</code> to <code>example</code>.</p>
<h2>Allowing bad inputs</h2>
<p>This last approach takes the first and second approaches above and combines them using a <code>pickOrDefault</code> function. Here if any value is passed into the partial, we will return it, except when that value would be incorrect in the output type:</p>
<div class="overflow-auto rounded-2xl bg-[#0e005d6d] p-4 font-mono text-sm dark:bg-[#0e005d6d] dark:text-gray-100"><pre><code class="language-tsx">function isValuePresent&lt;T extends object&gt;(obj: T, key: keyof T): boolean {
    return key in obj;
}

function pickOrDefault&lt;T extends object, K extends keyof T&gt;(partial: T, key: K, fallbackValue: T[K]): T[K] {
  if (key in partial) {
    return partial[key];
  }

  return fallbackValue
}

interface Foo {
  fieldA: string;
  fieldB?: string;
  fieldC?: boolean | null;
}

function makeFoo(partial: Partial&lt;Foo&gt; = {}): Foo {
  return {
	  fieldA: pickOrDefault(partial, &#x27;fieldA&#x27;, &#x27;test&#x27;) ?? &#x27;test&#x27;,
    fieldB: pickOrDefault(partial, &#x27;fieldB&#x27;, &#x27;example&#x27;),
    fieldC: pickOrDefault(partial, &#x27;fieldC&#x27;, true),
  };
}

const instance = makeFoo({ fieldA: undefined, fieldB: undefined });
console.log(instance.fieldA);
console.log(instance.fieldB);

console.log(instance.fieldA.toLowerCase());

</code></pre></div>
<p>For each field, we prefer the input partial, except here the type mismatch for <code>fieldA</code> forced us to add the default value twice, once if the partial didn’t have a value, and once if the partial had <code>undefined</code> which isn’t allows in the final version of <code>type Foo</code>.</p>
<p>While more verbose, this does eliminate the type holes the code!</p>

I've discussed [full and partial objects before on this blog](/blog/post/2023-08-14-partial-objects), and in this article I'm going to investigate a common factory pattern
in Typescript that can lead to type-holes.
When writing tests or complex components, I'll often create prop factory utilities.



For tests, the goal is to create props with all the default values, except a few that may be
overidden for a specific test case. The function signature typically looks like this:

```jsx
function makeFoo(partial?: Partial<Foo>): Foo;
```

The expectation is that a software developer can call `makeFoo` and get a version of `Foo` that has all the defaults set to use in tests. Then, if the developer want to override a few fields to test an edge case, all they do is call `makeFoo({ fieldA: 'special-case })`.

I’ve seen developers try to implement this a few ways, each with its pros and cons.

### Spreading

The easiest way to implement this function is to just provide defaults and spread the partial:

```jsx
interface Foo {
  fieldA: string;
  fieldB?: string;
  fieldC?: boolean | null;
}

function makeFoo(partial?: Partial<Foo>): Foo {
  return {
	  fieldA: 'test',
    fieldB: 'example',
    fieldC: false,
    ...partial
  };
}
```

Here, we create a `Foo`  mock with overrides for the defaults, which are provided by `partial?: Partial<Foo>` . However, even though `fieldA` is required, we can see a type-hole with the default Typescript compilation settings:

```jsx
const instance = makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });
console.log(instance.fieldA);

// No type error, but this blows up
console.log(instance.fieldA.toLowerCase());
```

When we spread, `undefined` actually overrides the default! But why were we allowed to provide `undefined` in the first place?

In Typescript, `Partial<Foo>`  keeps all the fields, but makes them optional. In the default compilation settings, an optional field can be set to `undefined`.

[Typescript Playground Link](https://www.typescriptlang.org/play/?#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkyDohbGMgtOjyXSToTA5TYDMQXamUx-oA9O-IAHJYYACeThQ0Cg6CguRk6jAyDAAAtgLQZNcAO6I9ROXCnc6Xa63e6PZ5FChdMDoAAy6GR0HEcDaDhCxyAA)

There is a Typescript compilation flag to throw a type-error and keep our sanity: `exactOptionalPropertyTypes`. Enabling this flag makes Typescript show an error for `makeFoo({ fieldA: undefined, fieldB: undefined, fieldC: undefined });`. We can add the field to the call if it is set to a value.

[Typescript Playground Link](https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTIAOSQ9BkANOwpnGRcNBkQAB5wFk7yeQUcYuI08CS0EPkEBAB0PS5uwB7sOrr6COb0yKD0ikjIALzIVrb2DtgNaTRGZBBEIBBkuevFmyDbu-uHqRInZ6D7yDohbGMgtOjyXSToTA5TYDMQLpXChPUbjd6Ar4-P4AoFFChdMDoAAy6AA7tBxHA2g4Qk8gA)

But this causes another problem: it is perfectly valid to create an initial instance of `Foo` without fieldB being set (and its value being `undefined`). But now our `makeFoo` object doesn’t allow us to pass `fieldB: undefined` anymore. Only when the interface explicitly defines fieldB as optional AND undefined does it allow us to so.

[Typescript Playground Link](https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=true#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQTZAB9kAVxBkIREBDJsCRUmQDCfZACNMJCHBCjkIcSRJsAvrlwxJCMMHQGAtnADWEDOgAUABzhR7OBINAAV-QJIAHk8APgBKGk8cdigIMHEoAzwASCVOShoAckh6QoAadjyVLiKIAA84Jx9dcsqOFVUaeBJaCAqCAgA6Yb8A4CD2cwsrBEd6ZFB6fSRkAF5kF3dPL2x27hpJaVl5ZHM4tlmQWnRdQZJ0Ji9FsGWIQeVyCnOZuZu3+8ez1e73yFEGYHQABl0AB3aCqOC9Lxxc5AA)

Generally this pattern without the flag is fine for creating mock data, since any type-holes would only be scoped to tests and not real production code. But the question is: can we have `makeFoo` take a partial, return Foo without type-holes, and have allow `undefined` for partials?

## Null-Coalescing Every Field

Another common implementation I have seen is to add nullish coalescing to every field:

```jsx
interface Foo {
  fieldA: string;
  fieldB?: string;
  fieldC?: boolean | null;
}

function makeFoo(partial?: Partial<Foo>): Foo {
  return {
	  fieldA: partial?.fieldA ?? 'test',
    fieldB: partial?.fieldB ?? 'example',
    fieldC: partial?.fieldC ?? false,
  };
} 
```

Let’s also turn off the `exactOptionalPropertyTypes` compilation flag for now.

We know every field will be set correctly, so there are no type-holes in `Foo`, however, we still have the problem where we cannot override a field to the `unset` value of `undefined` :

[Typescript Playground Link](https://www.typescriptlang.org/play/?exactOptionalPropertyTypes=false&ssl=13&ssc=2&pln=1&pc=1#code/JYOwLgpgTgZghgYwgAgGIHt3IN4ChnIzAQA2AJgIIBcyAzmFKAOYDc+hx5AQgPw32MQrdkVJkAwn2QAjTCQhwQyAD7IQAVxIk2AX1y4Y6kAjDB0SgLZwA1hAzoAFAAc4UU3BJSACq-ckAPPYAfACUNPY47FAQYOpQSngAkASi5NTILm7AHjwAdKmUyDw8yADkkPSlADTsKZxkXDSZfnkFXEUlpRAAHnAWTvLVtRxi4k2+2Z759eIdhB60EDUEOrr6COb0yKD0ikjIALzIVrb2DtgjaTRGZBBEIBBkVZcN1yC394-IOiFsGyC0dDyXIkdBMBw7MB7CDTMQUX64f6A4Gg8GQ6Gw7gIxGbIEw1EQgFQ4wwgoUXJgdAAGXQAHdoOI4IsHCEEUA)

Turning on the `exactOptionalPropertyTypes` also doesn’t save us here since we didn’t have a type-issue anyway, but more of a logic issue. `makeFoo({ fieldB: undefined })` will still set `fieldB` to `example`.

## Allowing bad inputs

This last approach takes the first and second approaches above and combines them using a `pickOrDefault` function. Here if any value is passed into the partial, we will return it, except when that value would be incorrect in the output type:

```tsx
function isValuePresent<T extends object>(obj: T, key: keyof T): boolean {
    return key in obj;
}

function pickOrDefault<T extends object, K extends keyof T>(partial: T, key: K, fallbackValue: T[K]): T[K] {
  if (key in partial) {
    return partial[key];
  }

  return fallbackValue
}

interface Foo {
  fieldA: string;
  fieldB?: string;
  fieldC?: boolean | null;
}

function makeFoo(partial: Partial<Foo> = {}): Foo {
  return {
	  fieldA: pickOrDefault(partial, 'fieldA', 'test') ?? 'test',
    fieldB: pickOrDefault(partial, 'fieldB', 'example'),
    fieldC: pickOrDefault(partial, 'fieldC', true),
  };
}

const instance = makeFoo({ fieldA: undefined, fieldB: undefined });
console.log(instance.fieldA);
console.log(instance.fieldB);

console.log(instance.fieldA.toLowerCase());

```

For each field, we prefer the input partial, except here the type mismatch for `fieldA` forced us to add the default value twice, once if the partial didn’t have a value, and once if the partial had `undefined` which isn’t allows in the final version of `type Foo`.

While more verbose, this does eliminate the type holes the code!

Forbidden Typescript: Spreading Type-holes

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    code: "code",
    li: "li",
    p: "p",
    ul: "ul",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "We all know that naming things is right up there in the top three most difficult things about programming, right next to concurrency and caching."
    }), "\n", _jsx(_components.p, {
      children: "For common utility functions, I typically follow a few rules to at least prefix the function names in a consistent and meaningful way. Some of these are borrowed from React Testing Library, whose naming scheme I like very much as it is internally consistent with the return types that certain classes of functions return, but also easy to memorize how they behave."
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "getFoo"
        }), " - “get” as a utility function prefix name should indicate that the function will return ", _jsx(_components.code, {
          children: "type Foo"
        }), " and that it is meant to be synchronous and without side-effects. Typically a ", _jsx(_components.code, {
          children: "getFoo"
        }), " would always return Foo from the current context or in-memory synchronous data store."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "queryFoo"
        }), " - functions with the prefix “query” should return ", _jsx(_components.code, {
          children: "type Promise<Foo>"
        }), ". Querying usually implies getting data asynchronously from an external data store and may have side-effects, let alone caching that data in a synchronous store for easier data-fetching in the future. I have also seen ", _jsx(_components.code, {
          children: "fetchFoo"
        }), " to indicate that the function will retrieve data from an external store, but I typically reserve ", _jsx(_components.code, {
          children: "fetch"
        }), " for low-level wrappers of the ", _jsx(_components.code, {
          children: "fetch"
        }), " utility."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "createFoo"
        }), " - similar to ", _jsx(_components.code, {
          children: "getXYZ"
        }), ", this creates a local, synchronously made instance of ", _jsx(_components.code, {
          children: "Foo"
        }), ". There may be side-effects here, but typically this function is idempotent. Following the pattern of ", _jsx(_components.code, {
          children: "typeOrm"
        }), " , creating an instance of ", _jsx(_components.code, {
          children: "Foo"
        }), " is NOT the same as making an instance with nice defaults. This instance of ", _jsx(_components.code, {
          children: "Foo"
        }), " might not have any data initialized, but may only come with the instance methods and unset variables."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "mutateFoo"
        }), " or ", _jsx(_components.code, {
          children: "saveFoo"
        }), " - create or update an instance of ", _jsx(_components.code, {
          children: "type Foo"
        }), ". Typically the only side-effect in these functions is storing the data in a cache, database, file, etc."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.code, {
          children: "makeFoo"
        }), " - this is very similar to ", _jsx(_components.code, {
          children: "createFoo"
        }), ", but this is typically reserved for mocks and default versions of ", _jsx(_components.code, {
          children: "Foo"
        }), ". For example, if you have a form with a lot of presets that a user is filling out, you might have a default version of the ", _jsx(_components.code, {
          children: "Foo"
        }), " object that you want to represent in your view state. When you extract that default, it would be returned in a ", _jsx(_components.code, {
          children: "makeFoo"
        }), " function (that might call ", _jsx(_components.code, {
          children: "createFoo"
        }), " in its internals to make an instance of ", _jsx(_components.code, {
          children: "Foo"
        }), "). Likewise, for mocks, you may want to make the process of creating a mock with a bunch of defaults simple, and have a function named ", _jsx(_components.code, {
          children: "createMockFoo"
        }), " with signature: ", _jsx(_components.code, {
          children: "createMockFoo(overrides?: Partial<Foo>): Foo"
        }), "."]
      }), "\n"]
    }), "\n", _jsxs(_components.p, {
      children: ["This is by no means an exhaustive list, but I do find it helpful to follow this pattern for code consistency and setting expectations with other software developers. If I write a function called ", _jsx(_components.code, {
        children: "getFoo"
      }), ", it shouldn’t query a database. If I write a ", _jsx(_components.code, {
        children: "makeFoo"
      }), " function, I would expect a nicely initialized ", _jsx(_components.code, {
        children: "Foo"
      }), " to pop out."]
    }), "\n", _jsxs(_components.p, {
      children: ["To me, following these conventions is similar to legalistic words like “must” and “can”. If we were to use these words in programming conventions, then ", _jsx(_components.code, {
        children: "mustXYZ"
      }), " would mean a function will ALWAYS return a value, no matter what, while ", _jsx(_components.code, {
        children: "canXYZ"
      }), " would mean the function could return ", _jsx(_components.code, {
        children: "null | undefined"
      }), " as well. Similarly, having some standard naming convention helps teams write code that others will understand without having to read jsdocs or dive deeper into the code every single time."]
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>We all know that naming things is right up there in the top three most difficult things about programming, right next to concurrency and caching.</p>
<p>For common utility functions, I typically follow a few rules to at least prefix the function names in a consistent and meaningful way. Some of these are borrowed from React Testing Library, whose naming scheme I like very much as it is internally consistent with the return types that certain classes of functions return, but also easy to memorize how they behave.</p>
<ul>
<li><code>getFoo</code> - “get” as a utility function prefix name should indicate that the function will return <code>type Foo</code> and that it is meant to be synchronous and without side-effects. Typically a <code>getFoo</code> would always return Foo from the current context or in-memory synchronous data store.</li>
<li><code>queryFoo</code> - functions with the prefix “query” should return <code>type Promise&lt;Foo&gt;</code>. Querying usually implies getting data asynchronously from an external data store and may have side-effects, let alone caching that data in a synchronous store for easier data-fetching in the future. I have also seen <code>fetchFoo</code> to indicate that the function will retrieve data from an external store, but I typically reserve <code>fetch</code> for low-level wrappers of the <code>fetch</code> utility.</li>
<li><code>createFoo</code> - similar to <code>getXYZ</code>, this creates a local, synchronously made instance of <code>Foo</code>. There may be side-effects here, but typically this function is idempotent. Following the pattern of <code>typeOrm</code> , creating an instance of <code>Foo</code> is NOT the same as making an instance with nice defaults. This instance of <code>Foo</code> might not have any data initialized, but may only come with the instance methods and unset variables.</li>
<li><code>mutateFoo</code> or <code>saveFoo</code> - create or update an instance of <code>type Foo</code>. Typically the only side-effect in these functions is storing the data in a cache, database, file, etc.</li>
<li><code>makeFoo</code> - this is very similar to <code>createFoo</code>, but this is typically reserved for mocks and default versions of <code>Foo</code>. For example, if you have a form with a lot of presets that a user is filling out, you might have a default version of the <code>Foo</code> object that you want to represent in your view state. When you extract that default, it would be returned in a <code>makeFoo</code> function (that might call <code>createFoo</code> in its internals to make an instance of <code>Foo</code>). Likewise, for mocks, you may want to make the process of creating a mock with a bunch of defaults simple, and have a function named <code>createMockFoo</code> with signature: <code>createMockFoo(overrides?: Partial&lt;Foo&gt;): Foo</code>.</li>
</ul>
<p>This is by no means an exhaustive list, but I do find it helpful to follow this pattern for code consistency and setting expectations with other software developers. If I write a function called <code>getFoo</code>, it shouldn’t query a database. If I write a <code>makeFoo</code> function, I would expect a nicely initialized <code>Foo</code> to pop out.</p>
<p>To me, following these conventions is similar to legalistic words like “must” and “can”. If we were to use these words in programming conventions, then <code>mustXYZ</code> would mean a function will ALWAYS return a value, no matter what, while <code>canXYZ</code> would mean the function could return <code>null | undefined</code> as well. Similarly, having some standard naming convention helps teams write code that others will understand without having to read jsdocs or dive deeper into the code every single time.</p>


We all know that naming things is right up there in the top three most difficult things about programming, right next to concurrency and caching.

For common utility functions, I typically follow a few rules to at least prefix the function names in a consistent and meaningful way. Some of these are borrowed from React Testing Library, whose naming scheme I like very much as it is internally consistent with the return types that certain classes of functions return, but also easy to memorize how they behave.

- `getFoo` - “get” as a utility function prefix name should indicate that the function will return `type Foo` and that it is meant to be synchronous and without side-effects. Typically a `getFoo` would always return Foo from the current context or in-memory synchronous data store.
- `queryFoo` - functions with the prefix “query” should return `type Promise<Foo>`. Querying usually implies getting data asynchronously from an external data store and may have side-effects, let alone caching that data in a synchronous store for easier data-fetching in the future. I have also seen `fetchFoo` to indicate that the function will retrieve data from an external store, but I typically reserve `fetch` for low-level wrappers of the `fetch` utility.
- `createFoo` - similar to `getXYZ`, this creates a local, synchronously made instance of `Foo`. There may be side-effects here, but typically this function is idempotent. Following the pattern of `typeOrm` , creating an instance of `Foo` is NOT the same as making an instance with nice defaults. This instance of `Foo` might not have any data initialized, but may only come with the instance methods and unset variables.
- `mutateFoo` or `saveFoo` - create or update an instance of `type Foo`. Typically the only side-effect in these functions is storing the data in a cache, database, file, etc.
- `makeFoo` - this is very similar to `createFoo`, but this is typically reserved for mocks and default versions of `Foo`. For example, if you have a form with a lot of presets that a user is filling out, you might have a default version of the `Foo` object that you want to represent in your view state. When you extract that default, it would be returned in a `makeFoo` function (that might call `createFoo` in its internals to make an instance of `Foo`). Likewise, for mocks, you may want to make the process of creating a mock with a bunch of defaults simple, and have a function named `createMockFoo` with signature: `createMockFoo(overrides?: Partial<Foo>): Foo`.

This is by no means an exhaustive list, but I do find it helpful to follow this pattern for code consistency and setting expectations with other software developers. If I write a function called `getFoo`, it shouldn’t query a database. If I write a `makeFoo` function, I would expect a nicely initialized `Foo` to pop out.

To me, following these conventions is similar to legalistic words like “must” and “can”. If we were to use these words in programming conventions, then `mustXYZ` would mean a function will ALWAYS return a value, no matter what, while `canXYZ` would mean the function could return `null | undefined` as well. Similarly, having some standard naming convention helps teams write code that others will understand without having to read jsdocs or dive deeper into the code every single time.


Thoughts on Naming Utility Functions

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    a: "a",
    h2: "h2",
    h3: "h3",
    li: "li",
    ol: "ol",
    p: "p",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "Below are some notes I’ve taken from setting up new code repositories and onboarding new team members. Hopefully they can help improve your current documentation and notes to make onboarding a smooth process."
    }), "\n", _jsx(_components.h2, {
      children: "Onboarding"
    }), "\n", _jsx(_components.p, {
      children: "When new members start, do you have processes and documentation in place to make onboarding easy?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Is your process written down?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Add a note for people onboarding continue to improve it when they walk through it. Every time a new members onboards, they should follow the documentation and update it with any missing steps or new errors and resolutions if they come across them."
    }), "\n", _jsx(_components.h2, {
      children: "Environment Setup"
    }), "\n", _jsx(_components.p, {
      children: "Part of onboarding is getting your environment set up. Usually, a team will have a preferred IDE and environment set up so that it is easy to help each other if there are any problems."
    }), "\n", _jsx(_components.p, {
      children: "☐ Is the preferred IDE documented?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Are preferred 3rd party plugins that developers install listed and documented somewhere?"
    }), "\n", _jsx(_components.p, {
      children: "☐ If there is a VPN, are all the VPN details documented?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Is the preferred Git usage documented? IE git-flow etc?"
    }), "\n", _jsx(_components.h2, {
      children: "README"
    }), "\n", _jsx(_components.p, {
      children: "Each repository should have a main README that acts as a starting point for people new to the project to read. This should be useful to people who have been at the company for years, all the way to someone new who has just received their laptop:"
    }), "\n", _jsx(_components.p, {
      children: "☐ Does the README have all the steps to:"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Download"
      }), "\n", _jsx(_components.li, {
        children: "Install"
      }), "\n", _jsx(_components.li, {
        children: "Run"
      }), "\n", _jsx(_components.li, {
        children: "Deploy"
      }), "\n", _jsx(_components.li, {
        children: "Test"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐ Architecture - Is the architecture documented? This doesn’t need to be all documented within the README, but the README should at least link out to external documentation that covers:"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Clients, servers, databases, 3rd party systems are documented"
      }), "\n", _jsx(_components.li, {
        children: "Data flows between systems are documented"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐  API Documentation - How is the API documented? This is similar to the architecture section."
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "If your repo has components, is there a Storybook or similar site to document the interfaces?"
      }), "\n", _jsx(_components.li, {
        children: "If your repo has web APIs, is there a OpenAPI spec that can be viewed?"
      }), "\n", _jsx(_components.li, {
        children: "Other projects will want to document their APIs as well."
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐ Design System - Similar to the API documentation, if there is a design system that is used or implemented, does your README call that out?"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Documentation - do you have a link to how to get to the documentation?"
      }), "\n", _jsx(_components.li, {
        children: "Storybooks - is there already a live storybook link somewhere? Does your README document how to run the storybook as well?"
      }), "\n"]
    }), "\n", _jsx(_components.h3, {
      children: "Building and CI/CD"
    }), "\n", _jsx(_components.p, {
      children: "If your project is buildable or deployable, do you have documentation on the Build Pipeline and the CI/CD PIipelines? These are important to simplify and document. Someone new to the project should be able to follow the README in the repo to build the application and understand what happens when they push a commit to the repository."
    }), "\n", _jsx(_components.p, {
      children: "☐  Build Pipeline"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Can the app be built in one step?"
      }), "\n", _jsx(_components.li, {
        children: "Is the pipeline modern?"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐  CI/CD"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Is there a CI/CD runner?"
      }), "\n", _jsx(_components.li, {
        children: "Is it documented?"
      }), "\n", _jsxs(_components.li, {
        children: ["Are there lint guidelines?", "\n", _jsxs(_components.ol, {
          children: ["\n", _jsx(_components.li, {
            children: "Are they checked on the CI/CD?"
          }), "\n"]
        }), "\n"]
      }), "\n", _jsxs(_components.li, {
        children: ["Are there unit tests?", "\n", _jsxs(_components.ol, {
          children: ["\n", _jsx(_components.li, {
            children: "Are they run on every commit?"
          }), "\n"]
        }), "\n"]
      }), "\n", _jsx(_components.li, {
        children: "Are there pre-push and pre-commit hooks? You can use Husky to set these up"
      }), "\n"]
    }), "\n", _jsx(_components.h3, {
      children: "Testing"
    }), "\n", _jsx(_components.p, {
      children: "As mentioned above, running unit, integration, and e2e tests may be part of the CI/CD pipeline. Will new people who onboard be able to follow the repo’s README or some other document in order to understand how to test their changes? If there is code-coverage, how do new members of the team know where to find them?"
    }), "\n", _jsx(_components.p, {
      children: "☐ Testing"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Is there a test pipeline"
      }), "\n", _jsx(_components.li, {
        children: "Are there unit tests"
      }), "\n", _jsx(_components.li, {
        children: "Are there automated code coverage reports?"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐ Bundle Sizes"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Make sure tree shaking is happening correctly"
      }), "\n", _jsx(_components.li, {
        children: "Analyze the bundle size with create-react-app or BundleSizeAnalyzer webpack plugin"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "☐ Performance"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsxs(_components.li, {
        children: ["Analyze your web app for pagespeed, lighthouse rating, and ", _jsx(_components.a, {
          href: "https://github.com/thecreazy/siteaudit",
          children: "a11y"
        })]
      }), "\n"]
    }), "\n", _jsx(_components.h3, {
      children: "External Services"
    }), "\n", _jsx(_components.p, {
      children: "Sometimes repositories are self-contained, but more often than not, a repository will pull external information from a service. This might be feature flags from providers like LaunchDarkly, or website content from a Content Management System (CMS). Do new members of the team need API keys for these services? Make sure to document any external services and how to access them."
    }), "\n", _jsx(_components.p, {
      children: "☐ CMS"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsx(_components.li, {
        children: "Are there a lot of text and content that is constantly updated?"
      }), "\n", _jsx(_components.li, {
        children: "Is there a CMS already implemented?"
      }), "\n"]
    }), "\n", _jsx(_components.h3, {
      children: "Conclusion"
    }), "\n", _jsx(_components.p, {
      children: "This is not meant to be an exhaustive list of everything to think about concerning onboarding members to a project. Documentation is nice to have, but working with the team to understand what is missing and how to improve it goes a long way to keeping the team happy and productive."
    }), "\n", _jsx(_components.p, {
      children: "I highly recommend reviewing the onboarding process from time to time and making sure that it is easy to onboard. You never know when your computer will crash and you need to set up your entire environment again."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>Below are some notes I’ve taken from setting up new code repositories and onboarding new team members. Hopefully they can help improve your current documentation and notes to make onboarding a smooth process.</p>
<h2>Onboarding</h2>
<p>When new members start, do you have processes and documentation in place to make onboarding easy?</p>
<p>☐ Is your process written down?</p>
<p>☐ Add a note for people onboarding continue to improve it when they walk through it. Every time a new members onboards, they should follow the documentation and update it with any missing steps or new errors and resolutions if they come across them.</p>
<h2>Environment Setup</h2>
<p>Part of onboarding is getting your environment set up. Usually, a team will have a preferred IDE and environment set up so that it is easy to help each other if there are any problems.</p>
<p>☐ Is the preferred IDE documented?</p>
<p>☐ Are preferred 3rd party plugins that developers install listed and documented somewhere?</p>
<p>☐ If there is a VPN, are all the VPN details documented?</p>
<p>☐ Is the preferred Git usage documented? IE git-flow etc?</p>
<h2>README</h2>
<p>Each repository should have a main README that acts as a starting point for people new to the project to read. This should be useful to people who have been at the company for years, all the way to someone new who has just received their laptop:</p>
<p>☐ Does the README have all the steps to:</p>
<ol>
<li>Download</li>
<li>Install</li>
<li>Run</li>
<li>Deploy</li>
<li>Test</li>
</ol>
<p>☐ Architecture - Is the architecture documented? This doesn’t need to be all documented within the README, but the README should at least link out to external documentation that covers:</p>
<ol>
<li>Clients, servers, databases, 3rd party systems are documented</li>
<li>Data flows between systems are documented</li>
</ol>
<p>☐  API Documentation - How is the API documented? This is similar to the architecture section.</p>
<ol>
<li>If your repo has components, is there a Storybook or similar site to document the interfaces?</li>
<li>If your repo has web APIs, is there a OpenAPI spec that can be viewed?</li>
<li>Other projects will want to document their APIs as well.</li>
</ol>
<p>☐ Design System - Similar to the API documentation, if there is a design system that is used or implemented, does your README call that out?</p>
<ol>
<li>Documentation - do you have a link to how to get to the documentation?</li>
<li>Storybooks - is there already a live storybook link somewhere? Does your README document how to run the storybook as well?</li>
</ol>
<h3>Building and CI/CD</h3>
<p>If your project is buildable or deployable, do you have documentation on the Build Pipeline and the CI/CD PIipelines? These are important to simplify and document. Someone new to the project should be able to follow the README in the repo to build the application and understand what happens when they push a commit to the repository.</p>
<p>☐  Build Pipeline</p>
<ol>
<li>Can the app be built in one step?</li>
<li>Is the pipeline modern?</li>
</ol>
<p>☐  CI/CD</p>
<ol>
<li>Is there a CI/CD runner?</li>
<li>Is it documented?</li>
<li>Are there lint guidelines?
<ol>
<li>Are they checked on the CI/CD?</li>
</ol>
</li>
<li>Are there unit tests?
<ol>
<li>Are they run on every commit?</li>
</ol>
</li>
<li>Are there pre-push and pre-commit hooks? You can use Husky to set these up</li>
</ol>
<h3>Testing</h3>
<p>As mentioned above, running unit, integration, and e2e tests may be part of the CI/CD pipeline. Will new people who onboard be able to follow the repo’s README or some other document in order to understand how to test their changes? If there is code-coverage, how do new members of the team know where to find them?</p>
<p>☐ Testing</p>
<ol>
<li>Is there a test pipeline</li>
<li>Are there unit tests</li>
<li>Are there automated code coverage reports?</li>
</ol>
<p>☐ Bundle Sizes</p>
<ol>
<li>Make sure tree shaking is happening correctly</li>
<li>Analyze the bundle size with create-react-app or BundleSizeAnalyzer webpack plugin</li>
</ol>
<p>☐ Performance</p>
<ol>
<li>Analyze your web app for pagespeed, lighthouse rating, and <a href="https://github.com/thecreazy/siteaudit">a11y</a></li>
</ol>
<h3>External Services</h3>
<p>Sometimes repositories are self-contained, but more often than not, a repository will pull external information from a service. This might be feature flags from providers like LaunchDarkly, or website content from a Content Management System (CMS). Do new members of the team need API keys for these services? Make sure to document any external services and how to access them.</p>
<p>☐ CMS</p>
<ol>
<li>Are there a lot of text and content that is constantly updated?</li>
<li>Is there a CMS already implemented?</li>
</ol>
<h3>Conclusion</h3>
<p>This is not meant to be an exhaustive list of everything to think about concerning onboarding members to a project. Documentation is nice to have, but working with the team to understand what is missing and how to improve it goes a long way to keeping the team happy and productive.</p>
<p>I highly recommend reviewing the onboarding process from time to time and making sure that it is easy to onboard. You never know when your computer will crash and you need to set up your entire environment again.</p>


Below are some notes I’ve taken from setting up new code repositories and onboarding new team members. Hopefully they can help improve your current documentation and notes to make onboarding a smooth process.

## Onboarding

When new members start, do you have processes and documentation in place to make onboarding easy?

☐ Is your process written down?

☐ Add a note for people onboarding continue to improve it when they walk through it. Every time a new members onboards, they should follow the documentation and update it with any missing steps or new errors and resolutions if they come across them.

## Environment Setup

Part of onboarding is getting your environment set up. Usually, a team will have a preferred IDE and environment set up so that it is easy to help each other if there are any problems.

☐ Is the preferred IDE documented?

☐ Are preferred 3rd party plugins that developers install listed and documented somewhere?

☐ If there is a VPN, are all the VPN details documented?

☐ Is the preferred Git usage documented? IE git-flow etc?

## README

Each repository should have a main README that acts as a starting point for people new to the project to read. This should be useful to people who have been at the company for years, all the way to someone new who has just received their laptop:

☐ Does the README have all the steps to:

1. Download
2. Install
3. Run
4. Deploy
5. Test

☐ Architecture - Is the architecture documented? This doesn’t need to be all documented within the README, but the README should at least link out to external documentation that covers:

1. Clients, servers, databases, 3rd party systems are documented
2. Data flows between systems are documented

☐  API Documentation - How is the API documented? This is similar to the architecture section.

1. If your repo has components, is there a Storybook or similar site to document the interfaces?
2. If your repo has web APIs, is there a OpenAPI spec that can be viewed?
3. Other projects will want to document their APIs as well.

☐ Design System - Similar to the API documentation, if there is a design system that is used or implemented, does your README call that out?

1. Documentation - do you have a link to how to get to the documentation?
2. Storybooks - is there already a live storybook link somewhere? Does your README document how to run the storybook as well?

### Building and CI/CD

If your project is buildable or deployable, do you have documentation on the Build Pipeline and the CI/CD PIipelines? These are important to simplify and document. Someone new to the project should be able to follow the README in the repo to build the application and understand what happens when they push a commit to the repository.

☐  Build Pipeline

1. Can the app be built in one step?
2. Is the pipeline modern?

☐  CI/CD

1. Is there a CI/CD runner?
2. Is it documented?
3. Are there lint guidelines?
    1. Are they checked on the CI/CD?
4. Are there unit tests?
    1. Are they run on every commit?
5. Are there pre-push and pre-commit hooks? You can use Husky to set these up

### Testing

As mentioned above, running unit, integration, and e2e tests may be part of the CI/CD pipeline. Will new people who onboard be able to follow the repo’s README or some other document in order to understand how to test their changes? If there is code-coverage, how do new members of the team know where to find them?

☐ Testing

1. Is there a test pipeline
2. Are there unit tests
3. Are there automated code coverage reports?

☐ Bundle Sizes

1. Make sure tree shaking is happening correctly
2. Analyze the bundle size with create-react-app or BundleSizeAnalyzer webpack plugin

☐ Performance

1. Analyze your web app for pagespeed, lighthouse rating, and [a11y](https://github.com/thecreazy/siteaudit)

### External Services

Sometimes repositories are self-contained, but more often than not, a repository will pull external information from a service. This might be feature flags from providers like LaunchDarkly, or website content from a Content Management System (CMS). Do new members of the team need API keys for these services? Make sure to document any external services and how to access them.

☐ CMS

1. Are there a lot of text and content that is constantly updated?
2. Is there a CMS already implemented?

### Conclusion

This is not meant to be an exhaustive list of everything to think about concerning onboarding members to a project. Documentation is nice to have, but working with the team to understand what is missing and how to improve it goes a long way to keeping the team happy and productive.

I highly recommend reviewing the onboarding process from time to time and making sure that it is easy to onboard. You never know when your computer will crash and you need to set up your entire environment again.


Reviewing Your Frontend Applications

<p>The following is a checklist I like to use to ensure I&#x27;m covering all the bases when building a component library. It&#x27;s a work in progress, but I hope it can be useful to others.</p>
<h2>Visual Language</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Color
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Palettes, by category</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Dark mode</li>
</ul>
</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Typography
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Headings</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Text</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Paragraph</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Lead paragraphs</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Readable text</li>
</ul>
</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Iconography
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Icons</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Meaning</li>
</ul>
</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Space
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Units / measurements</li>
</ul>
</li>
</ul>
<h2>Text</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Block quote</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Unordered list</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Ordered list</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Internal link</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  External link</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Code</li>
</ul>
<h2>Buttons</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Buttons
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Primary</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Secondary</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Button groups</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Menu buttons</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Split buttons</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Floating action button</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Brand buttons (Google, FB, Discord)</li>
</ul>
</li>
</ul>
<h2>Forms</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Form controls
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Text input</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Email/number/other variant inputs</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Multi-line text area</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Radio and radio group</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Checkbox and checkbox group</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Select</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  File upload</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Label</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Required label</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Switch</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Slider</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Calendar picker</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Rich text editor</li>
</ul>
</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Form structure</li>
</ul>
<h2>Layout</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Divider</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Box</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Marketing grid</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  App grid</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Page transitions</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Resopnsive breakpoints</li>
</ul>
<h2>Content</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Image</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Avatar</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Code block</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Footnotes</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Thumbnails</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Video</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Map widget</li>
</ul>
<h2>UI Components</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Alerts</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Accordion</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Back to top</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Badges/tags/chips/pills</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Breadcrumbs</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Caption</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Cards
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Panel</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Callout</li>
</ul>
</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Chat</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Comments</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Tables
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Data table</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Property table</li>
</ul>
</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Drawer</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Filters</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Footer</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Header</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Error (standard error handler)</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Loading / spinner / shimmer</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Toast</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Notification / badge (dot)</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Modal</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Pagination</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Popover</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Progress bar</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Search</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Sidebar</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Sort by</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Tabs</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Tooltips</li>
</ul>
<h2>Navigation</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Action bar / toolbar</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Main menu / Megamenu</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Inline menu</li>
</ul>
<h2>Marketing</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Contact us</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Cookie notification</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Hero billboard</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Hero carousel</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Legend</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Pull quote</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Ratings</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Reviews</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Social networking</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Status (alpha, beta)</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Tips / tutorial</li>
</ul>
<h2>UI Patterns</h2>
<ul class="contains-task-list">
<li class="task-list-item"><input type="checkbox" disabled=""/>  Authentication</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Create account</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Permissions</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Purchase/checkout</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Settings</li>
<li class="task-list-item"><input type="checkbox" disabled=""/>  Site / app structure</li>
</ul>


The following is a checklist I like to use to ensure I'm covering all the bases when building a component library. It's a work in progress, but I hope it can be useful to others.

## Visual Language

- [ ]  Color
  - [ ]  Palettes, by category
  - [ ]  Dark mode
- [ ]  Typography
  - [ ]  Headings
  - [ ]  Text
  - [ ]  Paragraph
  - [ ]  Lead paragraphs
  - [ ]  Readable text
- [ ]  Iconography
  - [ ]  Icons
  - [ ]  Meaning
- [ ]  Space
  - [ ]  Units / measurements

## Text

- [ ]  Block quote
- [ ]  Unordered list
- [ ]  Ordered list
- [ ]  Internal link
- [ ]  External link
- [ ]  Code

## Buttons

- [ ]  Buttons
  - [ ]  Primary
  - [ ]  Secondary
  - [ ]  Button groups
  - [ ]  Menu buttons
  - [ ]  Split buttons
  - [ ]  Floating action button
  - [ ]  Brand buttons (Google, FB, Discord)

## Forms

- [ ]  Form controls
  - [ ]  Text input
  - [ ]  Email/number/other variant inputs
  - [ ]  Multi-line text area
  - [ ]  Radio and radio group
  - [ ]  Checkbox and checkbox group
  - [ ]  Select
  - [ ]  File upload
  - [ ]  Label
  - [ ]  Required label
  - [ ]  Switch
  - [ ]  Slider
  - [ ]  Calendar picker
  - [ ]  Rich text editor
- [ ]  Form structure

## Layout

- [ ]  Divider
- [ ]  Box
- [ ]  Marketing grid
- [ ]  App grid
- [ ]  Page transitions
- [ ]  Resopnsive breakpoints

## Content

- [ ]  Image
- [ ]  Avatar
- [ ]  Code block
- [ ]  Footnotes
- [ ]  Thumbnails
- [ ]  Video
- [ ]  Map widget

## UI Components

- [ ]  Alerts
- [ ]  Accordion
- [ ]  Back to top
- [ ]  Badges/tags/chips/pills
- [ ]  Breadcrumbs
- [ ]  Caption
- [ ]  Cards
  - [ ]  Panel
  - [ ]  Callout
- [ ]  Chat
- [ ]  Comments
- [ ]  Tables
  - [ ]  Data table
  - [ ]  Property table
- [ ]  Drawer
- [ ]  Filters
- [ ]  Footer
- [ ]  Header
- [ ]  Error (standard error handler)
- [ ]  Loading / spinner / shimmer
- [ ]  Toast
- [ ]  Notification / badge (dot)
- [ ]  Modal
- [ ]  Pagination
- [ ]  Popover
- [ ]  Progress bar
- [ ]  Search
- [ ]  Sidebar
- [ ]  Sort by
- [ ]  Tabs
- [ ]  Tooltips

## Navigation

- [ ]  Action bar / toolbar
- [ ]  Main menu / Megamenu
- [ ]  Inline menu

## Marketing

- [ ]  Contact us
- [ ]  Cookie notification
- [ ]  Hero billboard
- [ ]  Hero carousel
- [ ]  Legend
- [ ]  Pull quote
- [ ]  Ratings
- [ ]  Reviews
- [ ]  Social networking
- [ ]  Status (alpha, beta)
- [ ]  Tips / tutorial

## UI Patterns

- [ ]  Authentication
- [ ]  Create account
- [ ]  Permissions
- [ ]  Purchase/checkout
- [ ]  Settings
- [ ]  Site / app structure


Component Library Checklist

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    a: "a",
    blockquote: "blockquote",
    h2: "h2",
    img: "img",
    li: "li",
    p: "p",
    ul: "ul",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "I’ve been experimenting with ChatGPT, just like everyone else. But why has it become so popular? It truly is a revolutionary piece of technology. Is it The Next Big Thing? Will it really replace all of us?"
    }), "\n", _jsx(_components.p, {
      children: "My day to day is architecture and programming, and I’ve heard all sorts of things on Twitter:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "That ChatGPT can build entire iOS applications"
      }), "\n", _jsx(_components.li, {
        children: "ChatGPT can write whole files of code"
      }), "\n", _jsx(_components.li, {
        children: "ChatGPT can find bugs in code when writing tests"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "When I started by own company Clarity Hub, we had a focus on machine learning to help augment human intelligence. My thought at the time was that we could leverage machine learning to augment and supplement human intelligence. The focus wouldn't be to replace any person's job, but to make it streamlined and easier to accomplish that job. Our journey started with us serving customer success agents with suggested replies and contextual information, but we eventually pivoted to a Dovetail-like application to help product teams gather, annotate, and contextualize customer interviews."
    }), "\n", _jsx(_components.p, {
      children: "We found that augmenting activity with machine learning was not only easier to do from a technology point of view, but empowered users, rather than make them feel like their job was being replaced."
    }), "\n", _jsx(_components.p, {
      children: "Even with the advent of ChatGPT, I still see this being the short term future of it's use."
    }), "\n", _jsx(_components.h2, {
      children: "False Starts"
    }), "\n", _jsx(_components.p, {
      children: "I was curious how much ChatGPT could really do given all of its hype"
    }), "\n", _jsx(_components.p, {
      children: "I asked it to build an Asteroids game using PhaserJS. Don’t worry, this isn’t another article on “Look, I got ChatGPT to build a game!”"
    }), "\n", _jsx(_components.p, {
      children: "I originally just asked ChatGPT to build an Asteroids game using PhaserJS. A very vague prompt, yes, but a great starting point to figure out the limitations of ChatGPT."
    }), "\n", _jsx(_components.p, {
      children: "The response was basically, “No I can’t”:"
    }), "\n", _jsxs(_components.blockquote, {
      children: ["\n", _jsx(_components.p, {
        children: "As an AI language model, I'm not able to write and execute code in real-time. However, I can provide you with a detailed framework to get started with creating an Asteroids game in PhaserJS."
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "This was followed by instructions on how I could do it myself."
    }), "\n", _jsx(_components.p, {
      children: "The next steps of course are to be more specific, asking ChatGPT to build the application to build specific functionality:"
    }), "\n", _jsxs(_components.blockquote, {
      children: ["\n", _jsx(_components.p, {
        children: "Add the code to let the player shoot asteroids. If the player gets hit by 3 asteroids, its game over"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "Most interactions with ChatGPT seem to go like this:"
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.img, {
        src: "/media/2023-07-23-chatgpt-coding-loop/Flowchart_Template_1.jpg",
        alt: "Flowchart workflow"
      })
    }), "\n", _jsx(_components.p, {
      children: "This flow eventually leads to either:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "Not getting what you want."
      }), "\n", _jsx(_components.li, {
        children: "Getting what you want across many different responses, and then you must manually coalesce all of the different responses together to form the result you want."
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "Once I like the set of responses that ChatGPT has given me, I’ll ask ChatGPT to summarize for me so that I can improve the prompt further:"
    }), "\n", _jsxs(_components.blockquote, {
      children: ["\n", _jsx(_components.p, {
        children: "Take everything we just talked about and give me a prompt to ask you in the future that encapsulates all of the requirements."
      }), "\n"]
    }), "\n", _jsx(_components.h2, {
      children: "A More Natural Flow"
    }), "\n", _jsxs(_components.p, {
      children: ["I’ve talked with ChatGPT on a variety of topics, but the majority of questions relate to coding. I actively use Github Copilot, which utilizes the ChatGPT engine in the backend. I’ve built ", _jsx(_components.a, {
        href: "https://marketplace.visualstudio.com/items?itemName=CapsuleCat.sora-by-capsule-cat",
        children: "Sora by Capsule Cat"
      }), " to have ChatGPT generate entire coding files for me as well with project context. Even then, I still use the ChatGPT UI as well."]
    }), "\n", _jsx(_components.p, {
      children: _jsx(_components.img, {
        src: "/media/2023-07-23-chatgpt-coding-loop/Flowchart_Template_2.jpg",
        alt: "Flowchart line"
      })
    }), "\n", _jsxs(_components.p, {
      children: ["I find that the above flow leaves me less fatigued, and more productive - at least in the context of side-projects that I’ve used ChatGPT. Research shows that when we read code and attempt logic puzzles, we use a completely different part of our brain than when we use language [", _jsx(_components.a, {
        href: "https://hub.jhu.edu/2020/12/17/brain-activity-while-reading-code/",
        children: "link"
      }), "]. In the above chart, you can imagine that when we write prompts, we utilize some logical reasoning, but we lean heavily on language as we talk with ChatGPT. Then when we get a response, a completely different part of the brain kicks in to read and write code."]
    }), "\n", _jsx(_components.h2, {
      children: "The Hard Part About Coding"
    }), "\n", _jsx(_components.p, {
      children: "Eventually this leads to “the hard part about coding” which anecdotally everyone will tell you that surprise, it isn’t the coding part. What is nice about ChatGPT though is that even though the hard part isn’t writing code, it does take time, thought, and energy."
    }), "\n", _jsx(_components.p, {
      children: "If the hard part of coding isn’t coding, then what is it? The non-exhaustive list is that it’s teamwork, communication, debugging, and requirements gathering. Oversimplifying, it’s the writing prompts part of the chart."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>I’ve been experimenting with ChatGPT, just like everyone else. But why has it become so popular? It truly is a revolutionary piece of technology. Is it The Next Big Thing? Will it really replace all of us?</p>
<p>My day to day is architecture and programming, and I’ve heard all sorts of things on Twitter:</p>
<ul>
<li>That ChatGPT can build entire iOS applications</li>
<li>ChatGPT can write whole files of code</li>
<li>ChatGPT can find bugs in code when writing tests</li>
</ul>
<p>When I started by own company Clarity Hub, we had a focus on machine learning to help augment human intelligence. My thought at the time was that we could leverage machine learning to augment and supplement human intelligence. The focus wouldn&#x27;t be to replace any person&#x27;s job, but to make it streamlined and easier to accomplish that job. Our journey started with us serving customer success agents with suggested replies and contextual information, but we eventually pivoted to a Dovetail-like application to help product teams gather, annotate, and contextualize customer interviews.</p>
<p>We found that augmenting activity with machine learning was not only easier to do from a technology point of view, but empowered users, rather than make them feel like their job was being replaced.</p>
<p>Even with the advent of ChatGPT, I still see this being the short term future of it&#x27;s use.</p>
<h2>False Starts</h2>
<p>I was curious how much ChatGPT could really do given all of its hype</p>
<p>I asked it to build an Asteroids game using PhaserJS. Don’t worry, this isn’t another article on “Look, I got ChatGPT to build a game!”</p>
<p>I originally just asked ChatGPT to build an Asteroids game using PhaserJS. A very vague prompt, yes, but a great starting point to figure out the limitations of ChatGPT.</p>
<p>The response was basically, “No I can’t”:</p>
<blockquote class="border-l-4 border-gray-300 pl-4">
<p>As an AI language model, I&#x27;m not able to write and execute code in real-time. However, I can provide you with a detailed framework to get started with creating an Asteroids game in PhaserJS.</p>
</blockquote>
<p>This was followed by instructions on how I could do it myself.</p>
<p>The next steps of course are to be more specific, asking ChatGPT to build the application to build specific functionality:</p>
<blockquote class="border-l-4 border-gray-300 pl-4">
<p>Add the code to let the player shoot asteroids. If the player gets hit by 3 asteroids, its game over</p>
</blockquote>
<p>Most interactions with ChatGPT seem to go like this:</p>
<p><img alt="Flowchart workflow" loading="lazy" width="1" height="1" decoding="async" data-nimg="1" class="mx-auto block !h-auto !w-auto max-h-[500px] max-w-full" style="color:transparent;width:auto;height:auto;max-width:100%;max-height:500px;margin:auto" src="/media/2023-07-23-chatgpt-coding-loop/Flowchart_Template_1.jpg"/></p>
<p>This flow eventually leads to either:</p>
<ul>
<li>Not getting what you want.</li>
<li>Getting what you want across many different responses, and then you must manually coalesce all of the different responses together to form the result you want.</li>
</ul>
<p>Once I like the set of responses that ChatGPT has given me, I’ll ask ChatGPT to summarize for me so that I can improve the prompt further:</p>
<blockquote class="border-l-4 border-gray-300 pl-4">
<p>Take everything we just talked about and give me a prompt to ask you in the future that encapsulates all of the requirements.</p>
</blockquote>
<h2>A More Natural Flow</h2>
<p>I’ve talked with ChatGPT on a variety of topics, but the majority of questions relate to coding. I actively use Github Copilot, which utilizes the ChatGPT engine in the backend. I’ve built <a href="https://marketplace.visualstudio.com/items?itemName=CapsuleCat.sora-by-capsule-cat">Sora by Capsule Cat</a> to have ChatGPT generate entire coding files for me as well with project context. Even then, I still use the ChatGPT UI as well.</p>
<p><img alt="Flowchart line" loading="lazy" width="1" height="1" decoding="async" data-nimg="1" class="mx-auto block !h-auto !w-auto max-h-[500px] max-w-full" style="color:transparent;width:auto;height:auto;max-width:100%;max-height:500px;margin:auto" src="/media/2023-07-23-chatgpt-coding-loop/Flowchart_Template_2.jpg"/></p>
<p>I find that the above flow leaves me less fatigued, and more productive - at least in the context of side-projects that I’ve used ChatGPT. Research shows that when we read code and attempt logic puzzles, we use a completely different part of our brain than when we use language [<a href="https://hub.jhu.edu/2020/12/17/brain-activity-while-reading-code/">link</a>]. In the above chart, you can imagine that when we write prompts, we utilize some logical reasoning, but we lean heavily on language as we talk with ChatGPT. Then when we get a response, a completely different part of the brain kicks in to read and write code.</p>
<h2>The Hard Part About Coding</h2>
<p>Eventually this leads to “the hard part about coding” which anecdotally everyone will tell you that surprise, it isn’t the coding part. What is nice about ChatGPT though is that even though the hard part isn’t writing code, it does take time, thought, and energy.</p>
<p>If the hard part of coding isn’t coding, then what is it? The non-exhaustive list is that it’s teamwork, communication, debugging, and requirements gathering. Oversimplifying, it’s the writing prompts part of the chart.</p>


I’ve been experimenting with ChatGPT, just like everyone else. But why has it become so popular? It truly is a revolutionary piece of technology. Is it The Next Big Thing? Will it really replace all of us?

My day to day is architecture and programming, and I’ve heard all sorts of things on Twitter:

- That ChatGPT can build entire iOS applications
- ChatGPT can write whole files of code
- ChatGPT can find bugs in code when writing tests

When I started by own company Clarity Hub, we had a focus on machine learning to help augment human intelligence. My thought at the time was that we could leverage machine learning to augment and supplement human intelligence. The focus wouldn't be to replace any person's job, but to make it streamlined and easier to accomplish that job. Our journey started with us serving customer success agents with suggested replies and contextual information, but we eventually pivoted to a Dovetail-like application to help product teams gather, annotate, and contextualize customer interviews.

We found that augmenting activity with machine learning was not only easier to do from a technology point of view, but empowered users, rather than make them feel like their job was being replaced.

Even with the advent of ChatGPT, I still see this being the short term future of it's use.

## False Starts

I was curious how much ChatGPT could really do given all of its hype  

I asked it to build an Asteroids game using PhaserJS. Don’t worry, this isn’t another article on “Look, I got ChatGPT to build a game!”

I originally just asked ChatGPT to build an Asteroids game using PhaserJS. A very vague prompt, yes, but a great starting point to figure out the limitations of ChatGPT.

The response was basically, “No I can’t”:

> As an AI language model, I'm not able to write and execute code in real-time. However, I can provide you with a detailed framework to get started with creating an Asteroids game in PhaserJS.

This was followed by instructions on how I could do it myself.

The next steps of course are to be more specific, asking ChatGPT to build the application to build specific functionality:

> Add the code to let the player shoot asteroids. If the player gets hit by 3 asteroids, its game over

Most interactions with ChatGPT seem to go like this:

![Flowchart workflow](/media/2023-07-23-chatgpt-coding-loop/Flowchart_Template_1.jpg)

This flow eventually leads to either:

- Not getting what you want.
- Getting what you want across many different responses, and then you must manually coalesce all of the different responses together to form the result you want.

Once I like the set of responses that ChatGPT has given me, I’ll ask ChatGPT to summarize for me so that I can improve the prompt further:

> Take everything we just talked about and give me a prompt to ask you in the future that encapsulates all of the requirements.

## A More Natural Flow

I’ve talked with ChatGPT on a variety of topics, but the majority of questions relate to coding. I actively use Github Copilot, which utilizes the ChatGPT engine in the backend. I’ve built [Sora by Capsule Cat](https://marketplace.visualstudio.com/items?itemName=CapsuleCat.sora-by-capsule-cat) to have ChatGPT generate entire coding files for me as well with project context. Even then, I still use the ChatGPT UI as well.

![Flowchart line](/media/2023-07-23-chatgpt-coding-loop/Flowchart_Template_2.jpg)

I find that the above flow leaves me less fatigued, and more productive - at least in the context of side-projects that I’ve used ChatGPT. Research shows that when we read code and attempt logic puzzles, we use a completely different part of our brain than when we use language [[link](https://hub.jhu.edu/2020/12/17/brain-activity-while-reading-code/)]. In the above chart, you can imagine that when we write prompts, we utilize some logical reasoning, but we lean heavily on language as we talk with ChatGPT. Then when we get a response, a completely different part of the brain kicks in to read and write code.

## The Hard Part About Coding

Eventually this leads to “the hard part about coding” which anecdotally everyone will tell you that surprise, it isn’t the coding part. What is nice about ChatGPT though is that even though the hard part isn’t writing code, it does take time, thought, and energy.

If the hard part of coding isn’t coding, then what is it? The non-exhaustive list is that it’s teamwork, communication, debugging, and requirements gathering. Oversimplifying, it’s the writing prompts part of the chart.


ChatGPT, Coding, and Language

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    a: "a",
    h2: "h2",
    p: "p",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "One of the first PC games I played was Starcraft and the expansion Starcraft: Broodwar. We didn’t have a PC, so I had to play it on a friend’s computer, but I remember being immersed in the real-time strategy gameplay."
    }), "\n", _jsxs(_components.p, {
      children: ["Later, I would get a PC and bought my own copy of Starcraft. This was years later, but the community for the game was still impressive. Joining one of the older Starcraft forums, I discovered “mods” for the game. The most popular ones were just graphical changes, but that concept of changing a game to display your own graphics was so interesting to me. I’m not sure how I stumbled on it, but I found ", _jsx(_components.a, {
        href: "http://www.staredit.net/",
        children: "http://www.staredit.net/"
      }), " (yes, it’s still active!) and I learned that you could do so much more than just change the graphics of Starcraft with mods. There were people in the community working on hooking into existing Starcraft code to modify the gameplay and graphics using C++."]
    }), "\n", _jsx(_components.h2, {
      children: "Diving deep"
    }), "\n", _jsx(_components.p, {
      children: "In order to create these mods, we needed to know the hex address of different functions that Starcraft would call during them game. And to do anything meaningful, we also needed to know the structure of units and sprites and where those were stored as well. A lot of this base work required using tools like OllyDbg to analyze the assembly of the Starcraft executable, and ArtMoney for analyzing the memory of the game while it was executing."
    }), "\n", _jsx(_components.p, {
      children: "I used OllyDbg to find what functions Starcraft would call during execution – from common functions like the game-loop, to highly specialized functions like checking supply limits. ArtMoney let us determine how structures like units were laid out – where each unit’s health was stored, how much damage each weapon would do, and more."
    }), "\n", _jsxs(_components.p, {
      children: ["Most of this information was shared in forums, chat rooms, and a few disparate sites for looking up hex addresses. Of course, no write up about modding Starcraft is complete without mentioning all the work from ShadowFlare (check out ", _jsx(_components.a, {
        href: "https://sfsrealm.hopto.org/",
        children: "ShadowFlare’s realm"
      }), " for all the work they did), the great people at Staredit.Net, and plenty of others who built amazing tools to work with Starcraft files. All these sites were amazing resources for figuring out file specs and working with the Starcraft engine."]
    }), "\n", _jsx(_components.p, {
      children: "However, each time I wanted to write a new mod or experiment with an idea, I’d have to look up all of this information across all of these sites."
    }), "\n", _jsx(_components.h2, {
      children: "Bringing it together"
    }), "\n", _jsx(_components.p, {
      children: "The goal with GPTP (General Plugin Template Project), was to take all of this work that the amazing modding community had done and bring it together into a C++ Visual Studio project that could be copied for a new mod."
    }), "\n", _jsx(_components.p, {
      children: "My initial idea was simple: take all of the code for injecting new function hooks into Starcraft and wrap it in some very friendly functions. When a modder would come in to create a new project, they would have three functions exposed to them to work with: gameStart, gameLoop, gameEnd (I don’t remember the exact names I gave them at the time)."
    }), "\n", _jsx(_components.p, {
      children: "I released the initial GPTP back in 2008-2009. This included the project setup for compiling and producing a QDP file that could be loaded into Starcraft. Additionally, it contained known structures and hex addresses that developers could use to build their mod. The Intellisense autocomplete feature really helped developers leverage these structures."
    }), "\n", _jsx(_components.h2, {
      children: "The power of open source"
    }), "\n", _jsx(_components.p, {
      children: "I made the original version of GPTP back in high school, but I didn’t have time to continue to work on it when I went to university. I returned to the community a decade later, and found that not only was the community still alive and working on mods, but that they were using GPTP. At this point, GPTP was unrecognizable from my original work; the goal was the same, but the quality of the code was greatly improved and the number of hooks, known structures, and addresses was much more impressive."
    }), "\n", _jsxs(_components.p, {
      children: ["You can view the project on Github: ", _jsx(_components.a, {
        href: "https://github.com/SCMapsAndMods/general-plugin-template-project",
        children: "general-plugin-template-project"
      }), "."]
    }), "\n", _jsx(_components.p, {
      children: "I’d like to thank open source for this sort of development. The amount of work that has been continually added onto this project couldn’t have been done without all the contributions from the community."
    }), "\n", _jsx(_components.h2, {
      children: "Does it still work?"
    }), "\n", _jsx(_components.p, {
      children: "I recently went back to Starcraft modding as a fun little project. I wanted to hop in and see how easy or difficult it would be to create a mod in 2020."
    }), "\n", _jsx(_components.p, {
      children: "One of the harder things to do in 2020 is find all the tools and initial setup for modding Starcraft. Some of the modding sites are down for good, and with them the knowledge they contained."
    }), "\n", _jsx(_components.p, {
      children: "But, I pulled together the tools (thanks PyMS), pulled together tutorials and other instructions into a Notion document, and created my first Starcraft mod!"
    }), "\n", _jsx(_components.p, {
      children: "Gathering all the tools was the hard part. After that, it was actually very straightforward creating a new GPTP template and mod. All of the known structures and hooks are pretty self-explanatory and I was able to even add my own hooks once I found the hex addresses using OllyDbg."
    }), "\n", _jsx(_components.h2, {
      children: "Looking forward"
    }), "\n", _jsx(_components.p, {
      children: "Starcraft modding is like an ancient art at this point. There isn’t a large audience for it, so in general, any new mod will be played by maybe 10 people. But to me, it’s a combination of nostalgia, hard work, tinkering, discovery, and creation that makes it so much fun. That feeling of finding a new function to hook onto, writing C++ code that injects itself into it, and then running the code in the Starcraft engine and seeing it work is a special kind of rewarding experience."
    }), "\n", _jsx(_components.h2, {
      children: "Thanks"
    }), "\n", _jsxs(_components.p, {
      children: ["I’d like to give thanks to everyone who has ever contributed to the modding community for Starcraft. There are so many names that I couldn’t possibly name them all, but please check of ", _jsx(_components.a, {
        href: "http://staredit.net",
        children: "http://staredit.net"
      }), " if any of this interests you."]
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>One of the first PC games I played was Starcraft and the expansion Starcraft: Broodwar. We didn’t have a PC, so I had to play it on a friend’s computer, but I remember being immersed in the real-time strategy gameplay.</p>
<p>Later, I would get a PC and bought my own copy of Starcraft. This was years later, but the community for the game was still impressive. Joining one of the older Starcraft forums, I discovered “mods” for the game. The most popular ones were just graphical changes, but that concept of changing a game to display your own graphics was so interesting to me. I’m not sure how I stumbled on it, but I found <a href="http://www.staredit.net/">http://www.staredit.net/</a> (yes, it’s still active!) and I learned that you could do so much more than just change the graphics of Starcraft with mods. There were people in the community working on hooking into existing Starcraft code to modify the gameplay and graphics using C++.</p>
<h2>Diving deep</h2>
<p>In order to create these mods, we needed to know the hex address of different functions that Starcraft would call during them game. And to do anything meaningful, we also needed to know the structure of units and sprites and where those were stored as well. A lot of this base work required using tools like OllyDbg to analyze the assembly of the Starcraft executable, and ArtMoney for analyzing the memory of the game while it was executing.</p>
<p>I used OllyDbg to find what functions Starcraft would call during execution – from common functions like the game-loop, to highly specialized functions like checking supply limits. ArtMoney let us determine how structures like units were laid out – where each unit’s health was stored, how much damage each weapon would do, and more.</p>
<p>Most of this information was shared in forums, chat rooms, and a few disparate sites for looking up hex addresses. Of course, no write up about modding Starcraft is complete without mentioning all the work from ShadowFlare (check out <a href="https://sfsrealm.hopto.org/">ShadowFlare’s realm</a> for all the work they did), the great people at Staredit.Net, and plenty of others who built amazing tools to work with Starcraft files. All these sites were amazing resources for figuring out file specs and working with the Starcraft engine.</p>
<p>However, each time I wanted to write a new mod or experiment with an idea, I’d have to look up all of this information across all of these sites.</p>
<h2>Bringing it together</h2>
<p>The goal with GPTP (General Plugin Template Project), was to take all of this work that the amazing modding community had done and bring it together into a C++ Visual Studio project that could be copied for a new mod.</p>
<p>My initial idea was simple: take all of the code for injecting new function hooks into Starcraft and wrap it in some very friendly functions. When a modder would come in to create a new project, they would have three functions exposed to them to work with: gameStart, gameLoop, gameEnd (I don’t remember the exact names I gave them at the time).</p>
<p>I released the initial GPTP back in 2008-2009. This included the project setup for compiling and producing a QDP file that could be loaded into Starcraft. Additionally, it contained known structures and hex addresses that developers could use to build their mod. The Intellisense autocomplete feature really helped developers leverage these structures.</p>
<h2>The power of open source</h2>
<p>I made the original version of GPTP back in high school, but I didn’t have time to continue to work on it when I went to university. I returned to the community a decade later, and found that not only was the community still alive and working on mods, but that they were using GPTP. At this point, GPTP was unrecognizable from my original work; the goal was the same, but the quality of the code was greatly improved and the number of hooks, known structures, and addresses was much more impressive.</p>
<p>You can view the project on Github: <a href="https://github.com/SCMapsAndMods/general-plugin-template-project">general-plugin-template-project</a>.</p>
<p>I’d like to thank open source for this sort of development. The amount of work that has been continually added onto this project couldn’t have been done without all the contributions from the community.</p>
<h2>Does it still work?</h2>
<p>I recently went back to Starcraft modding as a fun little project. I wanted to hop in and see how easy or difficult it would be to create a mod in 2020.</p>
<p>One of the harder things to do in 2020 is find all the tools and initial setup for modding Starcraft. Some of the modding sites are down for good, and with them the knowledge they contained.</p>
<p>But, I pulled together the tools (thanks PyMS), pulled together tutorials and other instructions into a Notion document, and created my first Starcraft mod!</p>
<p>Gathering all the tools was the hard part. After that, it was actually very straightforward creating a new GPTP template and mod. All of the known structures and hooks are pretty self-explanatory and I was able to even add my own hooks once I found the hex addresses using OllyDbg.</p>
<h2>Looking forward</h2>
<p>Starcraft modding is like an ancient art at this point. There isn’t a large audience for it, so in general, any new mod will be played by maybe 10 people. But to me, it’s a combination of nostalgia, hard work, tinkering, discovery, and creation that makes it so much fun. That feeling of finding a new function to hook onto, writing C++ code that injects itself into it, and then running the code in the Starcraft engine and seeing it work is a special kind of rewarding experience.</p>
<h2>Thanks</h2>
<p>I’d like to give thanks to everyone who has ever contributed to the modding community for Starcraft. There are so many names that I couldn’t possibly name them all, but please check of <a href="http://staredit.net">http://staredit.net</a> if any of this interests you.</p>


One of the first PC games I played was Starcraft and the expansion Starcraft: Broodwar. We didn’t have a PC, so I had to play it on a friend’s computer, but I remember being immersed in the real-time strategy gameplay.

Later, I would get a PC and bought my own copy of Starcraft. This was years later, but the community for the game was still impressive. Joining one of the older Starcraft forums, I discovered “mods” for the game. The most popular ones were just graphical changes, but that concept of changing a game to display your own graphics was so interesting to me. I’m not sure how I stumbled on it, but I found [http://www.staredit.net/](http://www.staredit.net/) (yes, it’s still active!) and I learned that you could do so much more than just change the graphics of Starcraft with mods. There were people in the community working on hooking into existing Starcraft code to modify the gameplay and graphics using C++.

## Diving deep

In order to create these mods, we needed to know the hex address of different functions that Starcraft would call during them game. And to do anything meaningful, we also needed to know the structure of units and sprites and where those were stored as well. A lot of this base work required using tools like OllyDbg to analyze the assembly of the Starcraft executable, and ArtMoney for analyzing the memory of the game while it was executing.

I used OllyDbg to find what functions Starcraft would call during execution – from common functions like the game-loop, to highly specialized functions like checking supply limits. ArtMoney let us determine how structures like units were laid out – where each unit’s health was stored, how much damage each weapon would do, and more.

Most of this information was shared in forums, chat rooms, and a few disparate sites for looking up hex addresses. Of course, no write up about modding Starcraft is complete without mentioning all the work from ShadowFlare (check out [ShadowFlare’s realm](https://sfsrealm.hopto.org/) for all the work they did), the great people at Staredit.Net, and plenty of others who built amazing tools to work with Starcraft files. All these sites were amazing resources for figuring out file specs and working with the Starcraft engine.

However, each time I wanted to write a new mod or experiment with an idea, I’d have to look up all of this information across all of these sites.

## Bringing it together

The goal with GPTP (General Plugin Template Project), was to take all of this work that the amazing modding community had done and bring it together into a C++ Visual Studio project that could be copied for a new mod.

My initial idea was simple: take all of the code for injecting new function hooks into Starcraft and wrap it in some very friendly functions. When a modder would come in to create a new project, they would have three functions exposed to them to work with: gameStart, gameLoop, gameEnd (I don’t remember the exact names I gave them at the time).

I released the initial GPTP back in 2008-2009. This included the project setup for compiling and producing a QDP file that could be loaded into Starcraft. Additionally, it contained known structures and hex addresses that developers could use to build their mod. The Intellisense autocomplete feature really helped developers leverage these structures.

## The power of open source

I made the original version of GPTP back in high school, but I didn’t have time to continue to work on it when I went to university. I returned to the community a decade later, and found that not only was the community still alive and working on mods, but that they were using GPTP. At this point, GPTP was unrecognizable from my original work; the goal was the same, but the quality of the code was greatly improved and the number of hooks, known structures, and addresses was much more impressive.

You can view the project on Github: [general-plugin-template-project](https://github.com/SCMapsAndMods/general-plugin-template-project).

I’d like to thank open source for this sort of development. The amount of work that has been continually added onto this project couldn’t have been done without all the contributions from the community.

## Does it still work?

I recently went back to Starcraft modding as a fun little project. I wanted to hop in and see how easy or difficult it would be to create a mod in 2020.

One of the harder things to do in 2020 is find all the tools and initial setup for modding Starcraft. Some of the modding sites are down for good, and with them the knowledge they contained.

But, I pulled together the tools (thanks PyMS), pulled together tutorials and other instructions into a Notion document, and created my first Starcraft mod!

Gathering all the tools was the hard part. After that, it was actually very straightforward creating a new GPTP template and mod. All of the known structures and hooks are pretty self-explanatory and I was able to even add my own hooks once I found the hex addresses using OllyDbg.

## Looking forward

Starcraft modding is like an ancient art at this point. There isn’t a large audience for it, so in general, any new mod will be played by maybe 10 people. But to me, it’s a combination of nostalgia, hard work, tinkering, discovery, and creation that makes it so much fun. That feeling of finding a new function to hook onto, writing C++ code that injects itself into it, and then running the code in the Starcraft engine and seeing it work is a special kind of rewarding experience.

## Thanks

I’d like to give thanks to everyone who has ever contributed to the modding community for Starcraft. There are so many names that I couldn’t possibly name them all, but please check of [http://staredit.net](http://staredit.net) if any of this interests you.


Revisiting GPTP - the Starcraft modding toolkit

"use strict";
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = {
    li: "li",
    p: "p",
    ul: "ul",
    ...props.components
  };
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "I was thinking about all the little projects I work on and how they grow over time. The applications end up hitting some milestones and end up needing similar functionality that compliments the core features. A small project ends up getting complex enough that it requires some unit tests. I’ll go to deploy the project and now I need some deployment scripts and analytics to ensure the application is running correctly. The technology may change between each project, but web applications always seem to have the same steps that need to be taken to strengthen the application as it is scaled up."
    }), "\n", _jsx(_components.p, {
      children: "At a large company, adding a new set of functionality always has a suite of concerns to think through before implementation: how will we deploy this feature, how do we validate that users are using the feature like we expected them to, how do we monitor for bugs and errors? This is on top of the basic functionality of actually writing and testing that new feature."
    }), "\n", _jsx(_components.p, {
      children: "What if we thought about this like Maslow’s Hierarchy of Needs, but in the context of a web application."
    }), "\n", _jsx(_components.p, {
      children: "Maslow's Hierarchy of Needs is a psychological model of human motivation proposed by Abraham Maslow in 1943. The model describes a hierarchy of human needs, beginning with basic physiological needs such as food and shelter and progressing upwards to higher-level needs such as self-actualization. Maslow argued that as humans satisfy their basic needs, they can move on to satisfy their higher-level needs."
    }), "\n", _jsx(_components.p, {
      children: "Applying Maslow's Hierarchy of Needs to web applications, we can identify the different levels of needs that need to be met in order to make a web application successful."
    }), "\n", _jsx(_components.p, {
      children: "Basic functionality:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "A single build/run script"
      }), "\n", _jsx(_components.li, {
        children: "Basic functionality (e.g. CRUD operations for a web app)"
      }), "\n", _jsx(_components.li, {
        children: "User interface (e.g. layout, navigation, responsive design)"
      }), "\n", _jsx(_components.li, {
        children: "Integration with external services (e.g. databases, APIs)"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "Safety and security:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "Linting (e.g. ESLint, Prettier)"
      }), "\n", _jsx(_components.li, {
        children: "Unit tests (e.g. Jest, Mocha)"
      }), "\n", _jsx(_components.li, {
        children: "Basic error handling and reporting (e.g. logging, alerting)"
      }), "\n", _jsx(_components.li, {
        children: "Input validation (e.g. form validation)"
      }), "\n", _jsx(_components.li, {
        children: "Security best practices (e.g. encryption, password hashing, session management)"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "Love and belonging:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "Basic analytics (e.g. page views, user engagement)"
      }), "\n", _jsx(_components.li, {
        children: "User authentication and authorization (e.g. sign-up, login, role-based access control)"
      }), "\n", _jsx(_components.li, {
        children: "User feedback (e.g. contact form, survey)"
      }), "\n", _jsx(_components.li, {
        children: "Social media integration (e.g. sharing, commenting)"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "Esteem:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "Advanced analytics (e.g. user behavior tracking, A/B testing)"
      }), "\n", _jsx(_components.li, {
        children: "Performance monitoring (e.g. load testing, monitoring of server resources)"
      }), "\n", _jsx(_components.li, {
        children: "User experience optimization (e.g. user testing, usability analysis)"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "Self-actualization:"
    }), "\n", _jsxs(_components.ul, {
      children: ["\n", _jsx(_components.li, {
        children: "End-to-end testing (e.g. Selenium, Cypress)"
      }), "\n", _jsx(_components.li, {
        children: "Accessibility and internationalization (e.g. support for screen readers, translation)"
      }), "\n", _jsx(_components.li, {
        children: "Scalability (e.g. load balancing, caching)"
      }), "\n", _jsx(_components.li, {
        children: "Continuous integration and delivery (e.g. Jenkins, Travis CI)"
      }), "\n", _jsx(_components.li, {
        children: "Deployment (e.g. Docker, Kubernetes)"
      }), "\n", _jsx(_components.li, {
        children: "Automated testing (e.g. unit test, integration test)"
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "Of course this list isn’t exhaustive, but I’ve been thinking about it as more of a checklist to build upon when working on small side-projects that end up getting significant attention and development time."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, {
    ...props,
    children: _jsx(_createMdxContent, {
      ...props
    })
  }) : _createMdxContent(props);
}
return {
  default: MDXContent
};


<p>I was thinking about all the little projects I work on and how they grow over time. The applications end up hitting some milestones and end up needing similar functionality that compliments the core features. A small project ends up getting complex enough that it requires some unit tests. I’ll go to deploy the project and now I need some deployment scripts and analytics to ensure the application is running correctly. The technology may change between each project, but web applications always seem to have the same steps that need to be taken to strengthen the application as it is scaled up.</p>
<p>At a large company, adding a new set of functionality always has a suite of concerns to think through before implementation: how will we deploy this feature, how do we validate that users are using the feature like we expected them to, how do we monitor for bugs and errors? This is on top of the basic functionality of actually writing and testing that new feature.</p>
<p>What if we thought about this like Maslow’s Hierarchy of Needs, but in the context of a web application.</p>
<p>Maslow&#x27;s Hierarchy of Needs is a psychological model of human motivation proposed by Abraham Maslow in 1943. The model describes a hierarchy of human needs, beginning with basic physiological needs such as food and shelter and progressing upwards to higher-level needs such as self-actualization. Maslow argued that as humans satisfy their basic needs, they can move on to satisfy their higher-level needs.</p>
<p>Applying Maslow&#x27;s Hierarchy of Needs to web applications, we can identify the different levels of needs that need to be met in order to make a web application successful.</p>
<p>Basic functionality:</p>
<ul>
<li>A single build/run script</li>
<li>Basic functionality (e.g. CRUD operations for a web app)</li>
<li>User interface (e.g. layout, navigation, responsive design)</li>
<li>Integration with external services (e.g. databases, APIs)</li>
</ul>
<p>Safety and security:</p>
<ul>
<li>Linting (e.g. ESLint, Prettier)</li>
<li>Unit tests (e.g. Jest, Mocha)</li>
<li>Basic error handling and reporting (e.g. logging, alerting)</li>
<li>Input validation (e.g. form validation)</li>
<li>Security best practices (e.g. encryption, password hashing, session management)</li>
</ul>
<p>Love and belonging:</p>
<ul>
<li>Basic analytics (e.g. page views, user engagement)</li>
<li>User authentication and authorization (e.g. sign-up, login, role-based access control)</li>
<li>User feedback (e.g. contact form, survey)</li>
<li>Social media integration (e.g. sharing, commenting)</li>
</ul>
<p>Esteem:</p>
<ul>
<li>Advanced analytics (e.g. user behavior tracking, A/B testing)</li>
<li>Performance monitoring (e.g. load testing, monitoring of server resources)</li>
<li>User experience optimization (e.g. user testing, usability analysis)</li>
</ul>
<p>Self-actualization:</p>
<ul>
<li>End-to-end testing (e.g. Selenium, Cypress)</li>
<li>Accessibility and internationalization (e.g. support for screen readers, translation)</li>
<li>Scalability (e.g. load balancing, caching)</li>
<li>Continuous integration and delivery (e.g. Jenkins, Travis CI)</li>
<li>Deployment (e.g. Docker, Kubernetes)</li>
<li>Automated testing (e.g. unit test, integration test)</li>
</ul>
<p>Of course this list isn’t exhaustive, but I’ve been thinking about it as more of a checklist to build upon when working on small side-projects that end up getting significant attention and development time.</p>


I was thinking about all the little projects I work on and how they grow over time. The applications end up hitting some milestones and end up needing similar functionality that compliments the core features. A small project ends up getting complex enough that it requires some unit tests. I’ll go to deploy the project and now I need some deployment scripts and analytics to ensure the application is running correctly. The technology may change between each project, but web applications always seem to have the same steps that need to be taken to strengthen the application as it is scaled up.

At a large company, adding a new set of functionality always has a suite of concerns to think through before implementation: how will we deploy this feature, how do we validate that users are using the feature like we expected them to, how do we monitor for bugs and errors? This is on top of the basic functionality of actually writing and testing that new feature.

What if we thought about this like Maslow’s Hierarchy of Needs, but in the context of a web application.

Maslow's Hierarchy of Needs is a psychological model of human motivation proposed by Abraham Maslow in 1943. The model describes a hierarchy of human needs, beginning with basic physiological needs such as food and shelter and progressing upwards to higher-level needs such as self-actualization. Maslow argued that as humans satisfy their basic needs, they can move on to satisfy their higher-level needs.

Applying Maslow's Hierarchy of Needs to web applications, we can identify the different levels of needs that need to be met in order to make a web application successful.

Basic functionality:

- A single build/run script
- Basic functionality (e.g. CRUD operations for a web app)
- User interface (e.g. layout, navigation, responsive design)
- Integration with external services (e.g. databases, APIs)

Safety and security:

- Linting (e.g. ESLint, Prettier)
- Unit tests (e.g. Jest, Mocha)
- Basic error handling and reporting (e.g. logging, alerting)
- Input validation (e.g. form validation)
- Security best practices (e.g. encryption, password hashing, session management)

Love and belonging:

- Basic analytics (e.g. page views, user engagement)
- User authentication and authorization (e.g. sign-up, login, role-based access control)
- User feedback (e.g. contact form, survey)
- Social media integration (e.g. sharing, commenting)

Esteem:

- Advanced analytics (e.g. user behavior tracking, A/B testing)
- Performance monitoring (e.g. load testing, monitoring of server resources)
- User experience optimization (e.g. user testing, usability analysis)

Self-actualization:

- End-to-end testing (e.g. Selenium, Cypress)
- Accessibility and internationalization (e.g. support for screen readers, translation)
- Scalability (e.g. load balancing, caching)
- Continuous integration and delivery (e.g. Jenkins, Travis CI)
- Deployment (e.g. Docker, Kubernetes)
- Automated testing (e.g. unit test, integration test)

Of course this list isn’t exhaustive, but I’ve been thinking about it as more of a checklist to build upon when working on small side-projects that end up getting significant attention and development time.


programming posts