The reviewer’s job is tiring and thankless. They have to:

1. understand the context of your change, such as the issue at hand
2. review your design to ensure that no other design is more feasible
3. review the actual code to ensure it is a high-quality implementation
4. test the implementation to ensure it actually works

In this blog, I present specific and actionable suggestions, so you can make it easy for any reviewer to review your changeset. The mantra is to reduce the diff and make it understandable. All of the following suggestions directly implement this mantra.

Reduce the diff

tl;dr: Reviewing 5 separate changesets is easier than one giant bundled changeset because smaller, focused changes are easier to understand, test, and validate. It reduces cognitive load, improves visibility into changes, and allows for more targeted feedback and testing.

Do not make unrelated code changes

It is easy to accidentally bundle code formatting or code refactoring changes in your primary changeset. Note that any formatting or refactoring change should always be in its own separate changeset. Your primary changeset that implements a bugfix should never also be renaming multiple variables or changing indentations.

As a rule of thumb: you can separate changesets by their effect on the application’s function. Any code refactor or formatting will likely be a non-functional changeset. Any bugfix or feature is likely a functional changeset. You should keep these changesets separate.

In practice, this separation makes the reviewer’s task easy: I know this changeset is only for code formatting, so any functional change is probably a mistake, and I should flag it.

Focus each changeset on one specific issue

When working on one bugfix, it is easy to find more bugs on the same feature. The natural tendency is to bundle their bugfixes together in the changeset. After all, all the bugs are related to the same feature, and you fixed them around roughly the same time.

Practically, when all the bugfixes are bundled in one changeset, most code review tools (like in GitLab/GitHub) will present one large diff for all bugfixes together. This makes it difficult for the reviewer to understand which part of the diff corresponds to which bugfix.

You should put each bugfix in its own dedicated changeset, as this gives the reviewer (and you) the ability to reason about each bugfix independently.

As a rule of thumb, write a simple one-sentence summary of your changeset, and if the changeset does more than just the summary, it should be split up.

Split large changesets into multiple sequential parts

Changesets that implement large features, such as a new user walkthrough, are very difficult to review. That is because often these changesets implement the core feature and also re-organize a lot of the related code. For example: they extract helper functions from existing code.

It usually makes sense to split out these reorganization changes into a dedicated changeset. This makes the reviewer’s task easy, because 1. this is a non-functional changeset, and 2. it reduces the size of the primary changeset (which would now be just the core feature).

The rule of thumb I follow is: I first write the feature changeset fully. Once it is done, then I extract the non-functional changes into a separate changeset and send that first.

Make the changeset understandable

tl;dr: Reviewing understandable changesets avoids needless asynchronous back-and-forth, and saves everyone time.

Explain confusing changes

You should always explain any change that is not immediately obvious. This saves the reviewer time from having to ask you a question, and you from having to respond to it. In asynchronous/remote teams, this saves everyone time.

As a rule of thumb, if I feel any part is confusing, I always explain it ahead of time, because the reviewer is likely to find it confusing too.

Explain alternative solutions for the same issue

The reviewer is also a subject matter expert just like you. They’re likely to think of other solutions to the same issue. If you have also thought about them, you should make that clear in the changeset. Specifically: which other solutions did you implement, and why did they fall short of the proposed solution?

Without your explanation, the reviewer will just be confused: Why didn’t we implement solution X which appears much simpler?

Add tests

Tests help the reviewer understand how a given bug manifests in practice. Tests also give the reviewer confidence that your implementation does fix that bug. Finally, tests clarify your thought process, because they describe all the instances that you consider relevant to the bug. This allows the reviewer to suggest any new instance which should also be tested in this changeset.

Conclusion

I hope you found the blog post useful. Feel free to reach out to me to continue the discussion.

If you have also been stuck in a similar debugging session, you would agree on the importance of note-taking. It helps you to track two primary parameters:

• what information is certainly known so far,
• what next steps we can take to extract more information

Now, the note-taking tool is insignificant compared to the skill in identifying those two parameters. But, the correct choice can still help you stay focused on the task at hand.

Back in the day, I wrote my debugging notes in Google Docs. Google Docs is great if you are working live with another team member. It is also great for writing colorful, “rich” debugging notes. If you prefer that kind of style, by all means, continue using it!

In this blog post, I will instead share an alternative: good old email. For solo debugging sessions, I have found email to be much better than Google Docs.

How I use email for note-taking while debugging

Each debugging session belongs to one very long email thread, that is sent to my own email address. While debugging, I write my latest observations in the latest email draft. When I feel confident about these observations, I send the email (to myself), and then start the next draft in that same email thread. I repeat this until I find all the info that I need.

Why I prefer email over Google Docs

“Commit”ing notes helps enforce progress over time

Writing notes in an email thread helps the debugging session to “move forward in time”. You cannot edit any past notes, as they have been “committed” to the email thread - like code is committed to a repository. You can only ever update the latest email draft: this restriction helps you focus on debugging. Every new email you send counts as a new stepping stone, getting you closer towards the final solution.

In Google Docs, there is no perspective of how notes were taken over time. Sure, you can try to enforce this visually, by writing the notes sequentially. In practice, this is hard to enforce. It is easy to start editing the older notes in the Google Doc while debugging, which can lead to wasted effort. More on this in the next section.

Focusing on the problem rather than the formatting

While in a debugging session, it is easy to get lost trying to make the notes in Google Docs “look good”. This might include:

1. cleaning up older notes in the light of latest observations,
2. putting bold or italics on certain phrases to draw attention to them
3. cleaning up the language and structure of the past sentences

None of this is useful when you’re already inside the debugging session. This distracts you from the core task of thinking about the potential solutions for the problem.

Email instead supports limited formatting, and it also prevents you from editing previously sent emails. This reduced area for exploration of the notes, forces you to explore the problem more.

In other words, the developer’s time is the most valuable and it is also the most limited. More time spent formatting the notes necessarily implies less time spent debugging the actual issue.

Email separates ongoing debugging research from a postmortem report

When writing notes in Google Docs, the writer might want to start tidying them up to be ready for the final presentation in the team meeting. Intuitively, this makes sense: by putting in an incremental effort to prepare the presentation, you lighten the extra workload when the debugging session ends.

Although intuitive, this is counter-productive. You cannot know in advance if the current chain of thought is in the right direction. You might spend time fleshing out specific thoughts, only to realize later they don’t matter in the final solution. Moreover, this again distracts you from the core task of debugging.

Conclusion

While debugging an issue, the primary aim for the engineer is to find a simple and reliable solution as soon as possible. While debugging, the engineer usually has a long train of thoughts, which should be written down, to help solidify those thoughts. A restrictive tool like email helps force the engineer to focus on debugging; whereas a free-form tool like Docs encourages exploration beyond what is necessary for the primary aim.

Introduction

Chrome extensions enable developers to extend the web platform with custom styling and/or custom interactivity ³. This implies that Chrome extension developers are usually Web Developers, as they can write the necessary JavaScript, CSS, and HTML. When the Chrome extension platform uses the basic Web APIs⁴, then the existing Web Developers can easily contribute to the Chrome extension platform.

Manifest V2

There are only two key components in the Manifest V2 platform: a background page and a content script. The background page:

• is a single instance that runs in the background of the Chrome browser. It starts when the Chrome browser starts, and is destroyed only when the Chrome process exits.
• is a page with DOM API access
• is a high-privilege context: here, you can store user data, run business logic, and access all chrome.* APIs.

On the other hand, the content script:

• has access to the target web page content (such as the DOM on youtube.com) and can manipulate it,
• is a short-lived script, so it dies out when that Chrome tab is closed.
• is a low-privilege context: mostly executes instructions that it receives from the background page via messaging.

Four example use cases with the background page

Using the Manifest V2 background page, let us see how to implement the following four example use cases:

Handling global session state

To create global state per new browser session, we can put a global variable at the top of our JavaScript file, and read/write to it, like so:

// at the start of our file
let isUserLoggedIn = false;

// ...read the state anywhere
if (isUserLoggedIn) { /* do something */ }
else { /* do something else */ }

// ...update the state from anywhere
onAuthStateChanged((user) => {
  if (user) { isUserLoggedIn = true; }
  else { isUserLoggedIn = false; }
});

Using setInterval or setTimeout

This is easy to do in a background page:

const interval = setInterval(() => {
  // my logic here
}, 60 * 1000); // runs once a minute

// ...if later needed to clear
clearInterval(interval);

Note that timers in background pages are subject to timer throttling, like any backgrounded tab. This doesn’t affect intervals for a minute or higher.

DOM API access

The background page can access any DOM API, like so:

// ...read/write persisted storage
localStorage.setItem('key', 'value');
const value = localStorage.getItem('key');

// ...manipulate the user clipboard
document.execCommand('paste', false);

// ...play audio
new Audio('file.mp3').play();

// ...check the user OS
navigator.appVersion.includes('Win')

Note that these are perhaps the most basic Web APIs. Imagine your first index.js and index.html project: it is likely you used one or more of these APIs.

Multi-process synchronization

There is only one JavaScript process - the background page. It can manage the entire extension, and run all the tasks on its own. Therefore, there is no synchronization overhead between multiple processes.

Overall, we observe that Manifest V2 supports the most basic Web API features in a consistent manner, enabling web developers to get started easily.

Manifest V3

Manifest V3 splits the background page into two separate processes: a service worker and an offscreen document.

The extension service worker is slightly similar to the Web API’s service worker. In particular, the extension service worker⁵:

• is a single instance process, that is responsible for managing the entire extension
• cannot access any DOM API
• is loaded only on demand - for example, when responding to an event
• is unloaded after 30 seconds (though some exceptions are available⁶) of inactivity

The offscreen document is identical to the background page - except it cannot access chrome.* APIs ⁷.

The extension service worker can perform many tasks on its own. However, when it needs to play audio, access the clipboard, run DOM operations, etc. (an in-exhaustive list is available⁸) - then it should message the offscreen document to perform that task. The offscreen document will then send a response back to the service worker.

Note that, in Manifest V2, the background page itself can manage all tasks on its own. However, in MV3, we need to setup a messaging channel between the extension service worker and the offscreen document to perform a few of these tasks.

Four example use cases with the extension service workers:

Let us now again see how to implement the same four example use cases, using an extension service worker this time:

Handling global session state

As per the docs, we need to design our service worker to be “resilient against unexpected termination” ⁶. This effectively prohibits storing global state in-memory.

Now, we need to use chrome.storage APIs, which are async and verbose:

// ...writing a key
chrome.storage.local.set({ key: value }).then(() => {
  console.log('Value was set');

  // ...reading a key
  chrome.storage.local.get(["key"]).then((result) => {
    console.log("Value currently is " + result.key);
  });
});

Using setInterval or setTimeout

Any setTimeout or setInterval that is longer than thirty seconds can unexpectedly terminate. Now, we need to use the chrome.alarms API. To create the alarm, we run code like so ⁹:

async function createAlarm() {
  const alarm = await chrome.alarms.get("my-alarm");

  if (!alarm) {
    await chrome.alarms.create({ periodInMinutes: 1 });
  }
}

createAlarm();

and then to handle when it is triggered:

chrome.alarms.onAlarm.addListener((alarm) => {
  if (alarm.name === 'my-alarm') {
    // ...my logic here
  }
});

DOM API access

Any code that uses DOM APIs needs to run in the offscreen document. This introduces extra complexity, such as:

1. handling the creation of offscreen document¹⁰
2. asynchronous message passing with the offscreen document. This entails that all functions in the call stack also need to be async.
3. ensuring the message to and the response from the offscreen document both are JSON serializable.

Multi-process synchronization

Now we need to split our business logic into two files that run in two separate processes. This introduces extra complexity, such as:

• What happens if the offscreen document runs into an async exception while responding to the service worker? ¹¹ Will the service worker then be unloaded after waiting over 30 seconds for a response?
• The code editor loses type-checking information on the data sent with the message, and the response received for the message.
• If we have multiple files being imported across the two files, we need to ensure that no code is unintentionally shared between the two processes. Otherwise, we can accidentally inflate our app’s bundle size.

Conclusion

This blog post is only a factual and in-exhaustive summary of changes from Manifest V2 to Manifest V3 for four specific use cases. The full reasoning behind the Manifest V3 migration is much more complex and out of scope for this blog post. The example use cases I have taken may not be relevant for your project. In other use cases, it may be possible that MV3 has improved the developer experience.

References

I’m very humbled by the insightful discussion on HackerNews. Really, thank you! I have now updated the blog post to address the comments. You can always view the diff on GitHub.

Introduction

As much as I dislike the class syntax in JavaScript, it used to be my default choice when I needed an object factory, with support for static and instance level properties.

I recently found a clean way to eliminate the class syntax while still maintaining these properties, and in this post, I’ll show you how.

Classy issues

Classes are plagued with issues, such as:

this is awkward

Having to write:

this.progressBar.addEventListener(this.handler.bind(this));

is much worse compared to:

progressBar.addEventListener(handler);

The this prefix is mandatory for every instance property, which increases code bloat. When passing methods around, you have to carefully rebind them to the correct object.

Regarding private properties

I initially wrote that classes don’t support private properties. That was completely wrong, as this MDN article mentions. Using private properties helps better encapsulate internal logic, that we don’t want external code to depend on. I’m glad JS classes support that.

Regarding readonly properties

I initially wrote that we cannot have instance properties that are public but readonly. For example, this is valid JavaScript:

class MyClass {
  static prop = 123;
}
MyClass.prop = 456;

As comments pointed out, you can define a getter instead:

class MyClass {
  static get prop() {
    return 123;
  }
}
MyClass.prop = 456; // doesn't change the value

Poor bundler optimization

If you are building a large class encapsulating some complex logic, you likely have dozens of private methods as “helper” methods, but only a few externally exposed methods. Unfortunately, build tools like terser or webpack cannot optimize them well. For example:

class MyClass {
  constructor() {
    this.prop = 5;
  }
  publicMethod() {
    this.property = 6;
  }
}
const unused = 5;
const instance = new MyClass();
console.log(instance.prop);

When optimized with npx webpack --mode production, this results in:

(()=>{const o=new class{constructor(){this.prop=5}publicMethod(){this.property=6}};console.log(o.prop)})();

Notice how: 1. the unused instance method is not removed, and 2. the name of this instance method is not simplified.

Poor linting experience

Unused methods and properties are never flagged by eslint (here’s an example class). This makes it difficult to refactor existing code.

// flagged
const unusedVar = 123;

class MyClass {
  // not flagged
  static unusedStaticProperty = 6;

  constructor() {
    // not flagged
    this.unusedProperty = 5;
  }
  
  // not flagged
  unusedMethod() {
    
  }
}

new MyClass();

Not hoisted up

As JavaScript developers, we expect functions (that are blocks of code) to be hoisted up in their own lexical scope. Sadly, classes do not share this same property, which leads to workarounds like these:

var MyClass = class MyClassInternal {
  // ...
};

This is not an issue when using module-oriented development. But if you are not using modules, then this becomes a hassle.

Example

Here is an example class that we can rewrite:

class Dog {
  static AVERAGE_HEIGHT_FT = 4;
  static AVERAGE_WEIGHT_KG = 100;
  static _PRIVATE_MAGIC_HEIGHT = 3.14;

  constructor(height, weight) {
    this.height = height;
    this.weight = weight;
    if (this.height === this._PRIVATE_MAGIC_HEIGHT) {
      this._privateMakeTaller();
    }
  }

  _privateMakeTaller() {
    this.height = Dog.AVERAGE_HEIGHT_FT + 1;
  }

  printHeight() {
    const status = this.height > Dog.AVERAGE_HEIGHT_FT ? 'taller' : 'not taller';
    console.log(`Your dog is ${this.height} ft tall. The dog is ${status} than the average height`);
  }

  static getAverageHeight() {
    console.log(`Average height for dogs is ${Dog.AVERAGE_HEIGHT_FT} ft`);
  }
}

This code has a mix of static and instance-level methods and properties. Let us assume we want to expose only three methods: constructor, printHeight and getAverageHeight. Notice the weight properties are unused, which we might automatically detect in our re-written version. We also have a secret method and a secret property, that we want to encapsulate well.

Closures to the rescue!

JavaScript closures are amazing. We can use them to emulate static properties, instance properties, private properties, as well as readonly properties. Here’s the rewritten version of the above class:

const Dog = (function createDogClass() {
  const AVERAGE_HEIGHT_FT = 4;
  const AVERAGE_WEIGHT_KG = 100;
  const _PRIVATE_MAGIC_HEIGHT = 3.14;

  function init(heightInput, weightInput) {
    let height = heightInput;
    const weight = weightInput;
    if (height === _PRIVATE_MAGIC_HEIGHT) {
      _privateMakeTaller();
    }

    function _privateMakeTaller() {
      height = AVERAGE_HEIGHT_FT + 1;
    }

    function printHeight() {
      const status = height > AVERAGE_HEIGHT_FT ? 'taller' : 'not taller';
      console.log(`Your dog is ${height} ft tall. The dog is ${status} than the average height`);
    }

    return {
      printHeight,
    };
  }

  function getAverageHeight() {
    console.log(`Average height for dogs is ${AVERAGE_HEIGHT_FT} kg`);
  }

  return {
    init,
    getAverageHeight,
  };
})();

Immediately, we see several advantages:

1. Unused properties are flagged by eslint (see example)
2. Webpack optimizes our code with variable renaming and dead code removal.
3. We have lesser code bloat thanks to removing this. and Dog. prefixes.
4. Our private and readonly properties are truly private and readonly now.

   As we discussed earlier, regular classes also support this.

How does this work?

Static scope

The scope inside createDogClass is the static scope. Variables and functions declared in this scope are shared by all instances. From this scope, we return an object of properties that are exposed externally. In this case, we return:

1. init which acts as our constructor, and
2. getAverageHeight which lets the users know the average height of dogs.

Notice how:

1. the magic height property is private, and
2. the average height property is public (exposed via getAverageHeight) but readonly

Instance-level scope

We replaced the constructor with an init function that does the same job. Now, to create an instance, we call Dog.init(...) (instead of new Dog(...)). Note that each invocation of init returns a new object instance, which also comes up with a separate lexical scope (very handy for us!)

From inside init, we return all publicly exposed properties. In this case, we only expose printHeight. Notice how:

1. _privateMakeTaller is a private method, and unique for every instance of Dog
2. the static properties from Dog scope are easily accessible.
3. height and weight values are not shared across instances (unique per instance)

Conclusion

I hope this post helped you understand how to rewrite JavaScript class syntax into closures.

Post conclusion

Motivated by the HN comments, here’s some additional considerations when using closure syntax to emulate classes:

1. Developer experience takes a hit because now the instanceof check no longer works. Further, the syntax Dog.init might be strange to use instead of the familiar new Dog
2. Every new object ships with a copy of all the methods, which is bad for memory optimization of the program.

Also, I don’t recommend that we start switching all classes to closures straightaway. With this blog post, I want to highlight the difference between the class pattern vs the closure pattern, and how each of them have their differences and advantages. The choice of which one to use is ultimately yours to make.

Further discussion

Mika Genic reached out to me via e-mail to provide a clever design that clearly defines a public interface while also avoiding an IIFE. Here’s an example:

function Dog(name) {
  // define public interface
  const self = Object.assign(this, {
    publicFn1,
  })

  // init private state
  let created = new Date()
 
  // call constructor
  constructor()

  return self
 
  // logic
  function constructor() { console.log(`dog created`) }
  function publicFn1() { console.log(`${privateFn1()}`) }
  function privateFn1() { return `${name} ${created}` }
}

let dog = new Dog(`Billy`)
dog.publicFn1()

Note that:

1. there is no IIFE, which makes understanding the code far simpler.
2. the public interface is clearly separated from the rest of the logic
3. You can use the traditional new keyword to construct objects from this class.
4. You can avoid this entirely.

Some readers will notice that this is very similar to the pre-ES6 way of declaring classes. Here’s an example post on StackOverflow.

…or why you should always double-check that StackOverflow answer you just read.

This is a short story of how a slow PowerShell command led me to its .NET internals.

I have to run an executable file with dedicated input and output files. For context, this executable is compiled from C++ (can also use Python), and it will read a million numbers from an input file and then output their sum to another file. I prefer to use I/O redirection for this task as it is semantically most correct in this context.

In Linux, I would simply do .\A.out < .\A.in > .\A.out. However, the input redirect (<) operator is “reserved for future use”, even in PS7! They probably just forgot to implement it ._.

Either way, I search for alternatives and find the first StackOverflow answer. Happily, I run its suggested command:

Get-Content .\A.in | .\A.exe > .\A.out

Now, pause and think. What can go wrong here? The PowerShell gurus probably know the answer, but the Linux/macOS users are in for an interesting investigation!

What went wrong

This command took a whopping 15 seconds! Clearly, no modern CPU should take 15 seconds to sum up a million numbers. So how did this happen?

Hypotheses

Arithmetic is very fast for fast CPUs. So, there has to be an issue with the I/O redirection being too slow. To test that, I wrote a different C program that uses freopen to redirect the input file to stdin. This program only took 0.36seconds, neat!

What if the issue is some weird MSVC implementation issue? So, I re-wrote the same program in Python, with similar timing results (slower with Get-Content, faster otherwise).

Analyzing the StackOverflow answer

It is clear that Get-Content is taking too long. But how can it be slow? The answer we copied read had over hundred upvotes, was over a decade old, and was viewed at least 70k times. It also had a comment explaining Get-Content sends the pipes the lines one by one.

Let’s check if at least that is true. A program that reads only the first ten lines of the file should output instantly. Here’s a sample:

accumulated_input = ""
for _ in range(10):
  accumulated_input += input() + "\n"
print(accumulated_input)

We run this with Get-Content .\A.in | python3 .\code.py. The program instantly prints the first ten lines!

Now we know that the StackOverflow answer is correct. What then is really wrong with Get-Content?

Notice the slowness

Note that the above program did not exit after printing the first ten numbers, which tells us that Get-Content was still running. In fact, our root issue is that Get-Content itself is just incredibly slow.

Searching for “why is powershell get-content so slow” reveals this blog that demystifies the snail speed. Get-Content adds a bunch of metadata (called NoteProperty) to the data it reads. Because it reads one line at a time, it adds metadata to every line it reads. For a file with a million lines, this metadata addition becomes painfully slow.

Luckily, we can force the metadata to be added in batches of lines. For example, let’s run the following command that adds the NotePropertys in batches of a thousand lines:

Get-Content .\A.in -ReadCount 1000 | .\A.exe > .\A.out

This is faster than our original code, but still takes over three seconds to complete, which is completely unacceptable. Interestingly, increasing the ReadCount slows the program even further.

Which means we need to continue digging deeper…

Diving into .NET internals

What is PowerShell? Primarily, it is a scripting language “built on the .NET Common Language Runtime (CLR). All inputs and outputs are .NET objects”.

Get-Content is a high-level function exposed to us, that is unusable for larger files and has no other high-level alternatives. So, we dive into the .NET internal classes.

There are various Read methods in System.IO.File, such as: ReadAllBytes, ReadAllLines, ReadLines, however, the method most relevant to us is: System.IO.File::ReadAllText. This method simply “opens a text file, reads all the text in the file into a string, and then closes the file”. For extremely large files, this may not fit into the memory. However, for only a million numbers, this is good enough. So, we now run:

Measure-Command { [System.IO.File]::ReadAllText('.\A.in') | .\A.exe > A.out }

This completes in 0.3seconds, just as fast as our Linux counterpart! 🎉

Conclusion

Always double check StackOverflow answers for critical cases. It cost me one problem out of four in Hacker Cup 2022. To be clear, the answer was not wrong, just that my use case for it was different. Fortunately, I qualified the round either way ^_^