An Introduction to Narrative Coding

Introduction What is Narrative Coding What are Web Components The App Itself Humble Beginnings Creating and Reading TODOs Final Thoughts Introduction Hi! My name is Andrew Steele, and I’m a Staff Software Engineer. I’ve been programming for over 20 years now, mostly in front-end web development, and one of my favorite techniques for ensuring clean, readable, and maintainable code is what I like to call "Narrative Coding". It’s a strategy that helps me stay on task while clearly communicating to colleagues at any skill level exactly what my code is doing and why. In this article, I’ll show you how to use Narrative Coding techniques in your own code, while also showing off the power and flexibility of Web Components, as we work together to build a very simple To-Do app. Even though the example code here will be written using JavaScript/Typescript, the tips and techniques should be applicable to any programming language. I'm going to skip several steps here and there so as not to bore you with the details, but if you want to see the whole app in its finished state you can check out the repo here. What is Narrative Coding At its most basic level, Narrative Coding is simply commenting your code and using descriptive variable and function names. Easy enough, right? The problem that many developers run into is a mindset that if you write clean code that it should be readable and self-describing without anything “extra”. But we’ve all run into “clean code” that takes extra brain power to interpret what it’s doing, let alone why. If you’ve ever taken over a legacy project that’s been around for a while, then you know how hard it can be to get started. First you have to interpret the file structure, then you have to figure out what each file does, and then, if you’re lucky or fastidious enough, you might be able to discern “why” it does what it does. Take for example this relatively straightforward function: function getX(arr) { return arr.reduce((acc, val) => { acc += val; return acc; }, 0); } Now, if you’re experienced with JavaScript and particularly array methods, you can figure out what this function does, but you will have to read it and think about it. Consider this same function, with a better function name and more comments. // Function to find the sum of an array of numbers function getArraySum(arr) { return arr.reduce((acc, val) => { // Add the current value to the accumulator acc += val; return acc; }, 0); // Accumulator starts at 0 } Note how with a couple small additions it becomes as easy as reading to see and understand what this function is and what it does! Once you know that “acc” is short for “accumulator”, and “val” is short for value, and that the function expects an array of numbers, it’s a cinch to figure out that we’re summing up the values of the array and returning that sum. This is a very basic example, but it illustrates the value of commenting your code like it was a story, and using descriptive variable names. But we can take this even further using type annotations, whether with Typescript (which is way beyond the scope of this article) or with JSDOC comments, which is my preference since it "just works" in JavaScript in most modern IDEs and text editors like Visual Studio Code. /** * Function to find the sum of an array of numbers * @param {number[]} arr * @returns {number} */ function getArraySum(arr) { return arr.reduce((acc, val) => { // Add the current value to the accumulator acc += val; return acc; }, 0); // Accumulator starts at 0 } With these simple additions we've increased our understandability greatly, and we get type checking in our editor! No more guessing what arr should be. What are Web Components To be honest, I don’t want to spend half the article explaining Web Components. The framework I am going to use here is called StencilJS, and here’s where you can read up on StencilJS and Web Components. StencilJS makes use of TypeScript rather than pure JavaScript, but the example code here should still be pretty easy to follow even if you're not familiar with either language. Short version: Web Components are a web technology that enables encapsulated and reusable code. They’re sometimes also called Custom Elements, as they can be used similarly to standard HTML elements like or . The App Itself Humble Beginnings Because this article is more about Narrative Coding than it is application development more generally, I chose to make a very, very simple app. This app will do the very basic CRUD (Create Read Update Destroy) for a todo list. It will not be pretty, but it will work. The first thing I do when starting a new project is to create an outline of what I want to accomplish. Often I will do this in a separate TODO file, but if I’m working on improving existing code then I will often make my outline within the code itself. He

Mar 12, 2025 - 00:27
 0
An Introduction to Narrative Coding
  • Introduction
  • What is Narrative Coding
  • What are Web Components
  • The App Itself
    • Humble Beginnings
    • Creating and Reading TODOs
    • Final Thoughts

Introduction

Hi! My name is Andrew Steele, and I’m a Staff Software Engineer. I’ve been programming for over 20 years now, mostly in front-end web development, and one of my favorite techniques for ensuring clean, readable, and maintainable code is what I like to call "Narrative Coding". It’s a strategy that helps me stay on task while clearly communicating to colleagues at any skill level exactly what my code is doing and why. In this article, I’ll show you how to use Narrative Coding techniques in your own code, while also showing off the power and flexibility of Web Components, as we work together to build a very simple To-Do app. Even though the example code here will be written using JavaScript/Typescript, the tips and techniques should be applicable to any programming language.

I'm going to skip several steps here and there so as not to bore you with the details, but if you want to see the whole app in its finished state you can check out the repo here.

What is Narrative Coding

At its most basic level, Narrative Coding is simply commenting your code and using descriptive variable and function names. Easy enough, right? The problem that many developers run into is a mindset that if you write clean code that it should be readable and self-describing without anything “extra”. But we’ve all run into “clean code” that takes extra brain power to interpret what it’s doing, let alone why.

If you’ve ever taken over a legacy project that’s been around for a while, then you know how hard it can be to get started. First you have to interpret the file structure, then you have to figure out what each file does, and then, if you’re lucky or fastidious enough, you might be able to discern “why” it does what it does.

Take for example this relatively straightforward function:

function getX(arr) {
  return arr.reduce((acc, val) => {
    acc += val;
    return acc;
  }, 0);
}

Now, if you’re experienced with JavaScript and particularly array methods, you can figure out what this function does, but you will have to read it and think about it. Consider this same function, with a better function name and more comments.

// Function to find the sum of an array of numbers
function getArraySum(arr) {
  return arr.reduce((acc, val) => {
    // Add the current value to the accumulator
    acc += val;
    return acc;
  }, 0); // Accumulator starts at 0
}

Note how with a couple small additions it becomes as easy as reading to see and understand what this function is and what it does! Once you know that “acc” is short for “accumulator”, and “val” is short for value, and that the function expects an array of numbers, it’s a cinch to figure out that we’re summing up the values of the array and returning that sum.

This is a very basic example, but it illustrates the value of commenting your code like it was a story, and using descriptive variable names. But we can take this even further using type annotations, whether with Typescript (which is way beyond the scope of this article) or with JSDOC comments, which is my preference since it "just works" in JavaScript in most modern IDEs and text editors like Visual Studio Code.

/**
 * Function to find the sum of an array of numbers
 * @param {number[]} arr
 * @returns {number}
 */
function getArraySum(arr) {
  return arr.reduce((acc, val) => {
    // Add the current value to the accumulator
    acc += val;
    return acc;
  }, 0); // Accumulator starts at 0
}

With these simple additions we've increased our understandability greatly, and we get type checking in our editor! No more guessing what arr should be.

What are Web Components

To be honest, I don’t want to spend half the article explaining Web Components. The framework I am going to use here is called StencilJS, and here’s where you can read up on StencilJS and Web Components. StencilJS makes use of TypeScript rather than pure JavaScript, but the example code here should still be pretty easy to follow even if you're not familiar with either language.

Short version: Web Components are a web technology that enables encapsulated and reusable code. They’re sometimes also called Custom Elements, as they can be used similarly to standard HTML elements like