DEV Community: Andrew Steele

An Introduction to Narrative Coding

Andrew Steele — Tue, 11 Mar 2025 23:07:20 +0000

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 <button> or <p>.

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. Here's the TODO list for this app:

- [ ] Setup a Stencil app
- [ ] Create the HTML base
- [ ] Create Web Components
  - [ ] todo-list-app
  - [ ] todo-item

Note that this is a very simple and short list right now. I can always expand it as I go, adding more todos as I discover more things that need to be done along the way.

Reminder that you can check out the repo here.

First I'll setup the Stencil app and the HTML "base" where the app will live. Then I'll create at least two components: the todo-list-app where the application state will live, and a reusable todo-item component I can use to represent each todo. Once I've got the basics out of the way, I'll work on wiring things together.

Setting up Stencil is fairly straightforward but does require a couple extra steps. After running npm init stencil and selecting component, I then had to also run npm install @stencil/core@latest --save-exact to update Stencil from 4.7.0 to 4.27.0. After that, I had to clear out the "starter" content (a name formatting utility and an example "my-component" component).

Then I used npm run generate to create "skeleton" components for todo-list-app and todo-item. You have the option when you use this command to generate components to also generate CSS, .spec (functional tests), and .e2e (End-to-end tests) files. I may or may not use them all, but I went ahead and generated them all to start out.

Next, I added <h1>Todo List App</h1> to the todo-list-app component, added the todo-list-app component to the index.html file, and fired up the server to make sure everything was working correctly (npm start). So far so good!

We'll need a way of creating todos, so I'll add an input and a button. They won't do anything yet, but that's next!

Now we can check off the first several things on the TODO list, and add some more TODOs.

TODOs

- [x] Setup a Stencil project
- [x] Create the HTML base
- [x] Create Web Components
  - [x] todo-list-app
  - [ ] todo-item
- [ ] Tie todo-list-app button to `createTodo` function (create)
- [ ] Make todo-list-app display (read) todo-item components for each todo
- [ ] Make it possible to edit (update) a todo-item
- [ ] Make it possible to delete (destroy) a todo-item

Note that these new todos encompass all of the CRUD actions we want to support in our app.

Creating and Reading TODOs

We're going to need some way of keeping track of what TODOs exist, and so this is where traditionally we'd bring in some kind of state manager. We're not going to get that fancy here, and instead each todo-item will keep track of its 'state' by itself. If the todo-item exists, then the task isn't done yet. If the task is done, the todo-item disappears.

Before we can create a todo, we need to create a todo-item, so let's do that. Here's what the first version of todo-item's code looks like:

export class TodoItem {
  // This is the text of the to-do
  @Prop() text: string;

  render() {
    return (
      <Host>
        <div>
          <span>{this.text}</span>
          <button>Edit</button>
          <button>Delete</button>
          <button>Done</button>
        </div>
      </Host>
    );
  }
}

As you can see, we have a @Prop provided by Stencil to define a property on the custom element, which looks like this: <todo-item text="Test Item"></todo-item>. We then render that out to the screen using JSX like so: {this.text}.

In order to dynamically create a todo-item, we have to go to the todo-list-app component and wire up the input and button we created earlier. Here's how I'd code my outline for this next step inside that component:

export class TodoListApp {
  // Creates a new todo-item given the value of #todo-input
  private handleNewTodo() {
    // Get the value of #todo-input

    // Check that the text isn't an empty string

    // If not empty, create a new todo-item and add it to the DOM

    // Reset #todo-input
  }

  render() {...}
}

Remember, first we create an outline of what we want to code, and then we write the code to fit the narrative outline. You can probably already guess what this function will look like based on just this outline!

export class TodoListApp {
  @Element() el!: HTMLElement;

  // Creates a new todo-item given the value of #todo-input
  private handleNewTodo(): void {
    // Get the value of #todo-input
    const input = this.el.querySelector("#todo-input") as HTMLInputElement;
    const text = input.value;

    // Check that the text isn't an empty string
    if (text && text !== "") {
      // If not empty, create a new todo-item
      const newTodo = document.createElement("todo-item");

      // Set the text prop on the new todo
      newTodo.setAttribute("text", text);

      // Add the new todo to the list of todos
      const todoList = this.el.querySelector("#todo-list");
      todoList.appendChild(newTodo);
    }

    // Reset #todo-input
    input.value = "";
  }

  render() {
    return (
      <Host>
        <h1>Todo List App</h1>
        <input type="text" id="todo-input"></input>
        <button id="new-todo-button" onClick={this.handleNewTodo.bind(this)}>
          Add Todo
        </button>
        <div id="todo-list"></div>
      </Host>
    );
  }
}

Notice that I added a few more comments and reordered as needed. That's OK! Sometimes we discover an extra step or two as we go, and so we adapt our outline comments to fit the real world.

Now, are all of these comments strictly necessary? No, at this point I could probably remove half of them and most people looking at this code would still be able to understand what's going on. But here's the beautiful part about adding all these extra comments: they're free. When the compiler or whatever bundling tool you use compresses your code, it strips out the comments! So they don't take up any extra bytes. And those extra-long and descriptive variable and function names? They get replaced with one or two letters, so you might as well make them long and easy to understand when you're working on them!

This means we now get to check off two more items on our TODO list:

TODOs

- [x] Tie todo-list-app button to `createTodo` function (create)
- [x] Make todo-list-app display (read) todo-item components for each todo
- [ ] Make it possible to edit (update) a todo-item
- [ ] Make it possible to delete (destroy) a todo-item

Final Thoughts

I think by now you probably have a good sense of how this works, so I recommend just checking out the repo if you're curious how the rest of the code turned out. You might notice that I consolidated the "delete" and "done" buttons into a single "done" button, since they do the same thing.

I hope that this guide has helped you to think about how to better tell stories with your code. It makes it easier to read and understand, and helps whoever comes after you to know what decisions you made with your code and why, which aids in maintainability.

Feel free to reach out to me if you have any questions, comments, concerns, or suggestions!

hafcaf - The No-Framework SPA Solution for Everyone

Andrew Steele — Fri, 03 May 2019 03:00:33 +0000

Think about the last time you had to learn a new front end framework. It might have been React, or Vue, or maybe you’ve been scared to learn any of them because of how much ”stuff” you have to learn and do before you even start. Did you know React has 42 pages of “guides” to help developers know the “right” way to program with React? Vue and Angular both have 31. Then there’s the size; it’s common for the final size of your app’s code to be measured in megabytes, meaning your users can wait several seconds before anything displays on the screen.

Don’t even get me started on the ecosystem of build tools.

So there I was, fed up with having to carry in my head these huge frameworks with all their nuances, and I decided there had to be a better way. A way to return to a simpler time, when you didn’t have to have a manual handy to be able to do the simplest tasks. Failing to find what I was looking for, I made my own solution.

hafcaf weighs in at less than 1KB when minified and gzipped. It features only two pages of docs: a tutorial, and the API specifications. It requires you to learn only three methods: init, addRoute, and updateRoute. There’s only one (optional) lifecycle hook: onRender. Best of all, if you don’t want or need any of the JavaScript pieces, you can ditch them and the CSS-based routing function will still work.

hafcaf really does let you have as little JavaScript as you want while offering just enough to make website and web app development a lot less painful. You can check it out here on GitHub.

How the Magic Happens

hafcaf was inspired by an article by Heydon Pickering. Here’s the gist: instead of JavaScript-powered URL re-routing - which often requires server-side directives to redirect all URLs to your index.html file - hafcaf uses CSS-based routing using the :target pseudo-class. This pseudo-class automatically responds to anchor tags that point to internal IDs using the href="#link" syntax.

Don't worry, it's much easier than it sounds. Here's an example. Given this incredibly stripped-down example webpage code:

<main>
  <section id="section1">
    I'm the content for section one.
    <a href="#section2">Section Two</a>
    <a href="#home">Home</a>
  </section>
  <section id="section2">
    I'm the content for section two.
    <a href="#section1">Section One</a>
    <a href="#home">Home</a>
  </section>
  <section id="home">
    I'm the content for the Home page.
    <a href="#section1">Section One</a>
    <a href="#section2">Section Two</a>
  </section>
</main>

Using hafcaf, if you point your browser to yourdomain.com/#section2, then the content for section 2 would show instead of both sections' content. hafcaf does this by hiding all content that isn’t being targeted, effectively showing only one 'page’ of content at a time. By default, hafcaf shows the last block of content; in the example above, “home” would show by default.

Up to this point, we haven't needed to use any JavaScript at all. If static page loading meets you where you're at and provides all you need, then, by all means, don't bother loading the JavaScript file! That's the whole point of this library: you can have as little JavaScript in your site/app as you want, without sacrificing the speed and UX goodness of a SPA.

A Little JavaScript Goes a Long Way

If you don't mind a little bit of JavaScript in your codebase and want some fancy features like dynamic and/or lazy page loading, hafcaf’s JavaScript module gives you what you need - and nothing else.

Support for asynchronous/dynamic page loading
Support for lazy-loading (only request and load content when the user requests to view it)
Automatic population and activation of a navigation menu (e.g. setting a menu item with a .active class)
Addition of onRender actions which fire if and when a page is loaded

There are a few different ways to make use of the dynamic page loading functionality, but the key parts boil down to two API methods: addRoute and updateRoute. What these methods do is probably pretty self-explanatory: addRoute adds a route entry to hafcaf's collection of routes, and updateRoute modifies the content and/or settings.

The process basically looks like this: create a ‘page object’ with the basic information about your page, register it with hafcaf using the addRoute function, then go and fetch your page’s content in whichever way you like (I recommend fetch), and then finally call updateRoute with the actual content of the page.

It may seem like a lot of steps, but it’s easier than you might think. hafcaf was designed to handle ‘asynchronous’ content in a very graceful way, that will fit into any flow or framework with ease. Starting with the previous example, let’s add a new page called page 3.

<!-- page3.html -->
<div id="page-three">
    <h1>Page 3</h3>
  <p>Even moar content.</p>
</div>

Note that there’s no extra DOCTYPE, head, or body sections, only the content we want for this new page. This is because we’re going to inject it directly into the existing page, so it doesn’t need all the extra definitions of a normal HTML file.

Next, in your site’s main JavaScript file (or even in the index.html, if you want), set up the hafcaf.addRoute() function with an optional linkLabel property specified:

var exampleDynamicView = {
  id: "page-3",
  linkLabel: "Page 3"
};

hafcaf.addRoute(exampleDynamicView);

This linkLabel property tells hafcaf to add a new entry to the page's menu with the label we specified, "Page 3". This extra property is optional if you want to define your menu in a different way, or if you don't have a menu.

Now that you have a placeholder for your page, go and get the actual content. I prefer using fetch(), so here’s how I’d do it:

fetch("https://yourserver.it/pages/page3.html")
  .then(response => response.text())
  .then(innerHTML => ({ innerHTML, id: "page-3" }))
  .then(page => hafcaf.updateRoute(page));

Note that we process the response as text, then we assign that text to the innerHTML property of the new page object. If we had already had this content - maybe by fetching it earlier - we could have passed this same page object to addRoute() instead of updateRoute(); they work very similarly.

What else?!?

hafcaf has lots more features too, including an onRender() lifecycle hook you can use to set up things like event handlers (e.g. onClick) or subscriptions to streams or web sockets - complete with an exitFunctions collection you can add any disposer functions to. Through a couple of plugin-like additions, you can also get access to hafcaf Barista which helps automate the fetch-and-update pattern I showed you above, and hafcaf Tamper - a simple templating language. Coming soon, I plan to add hafcaf Roaster for handling query params (they basically get ignored right now), and the one I’m most excited about: hafcaf Refill - an implementation of the Observer pattern that will leverage hafcaf Tamper to give you automatically-updating views; just like those fancy frameworks, but with much less cost.

My main goal with hafcaf is to give people a simpler option. hafcaf isn’t meant to replace complex frameworks when you have to make complex applications. You’re not going to be making a 2D side-scroller with it. But for the majority of websites and apps that focus on displaying content with little or no ‘interactive’ parts, hafcaf might just make things simpler and easier.

Check it out here on Github.

Which Array Function When?

Andrew Steele — Tue, 08 Aug 2017 14:06:57 +0000

There's a lot of hullaballoo some days about "you should use reduce more" or "you don't need a filter, use a map", or "For? Why not forEach?"

The truth is, Arrays and all of their iterator functions can be confusing for beginners, so I'm going to try and simplify things for everyone by framing the question from the end: what do you want to get back?

Short version

Return one thing for each existing thing: map()
Return only some of the existing things: filter()
Return only one new thing: reduce()
Don't return anything, but do something with each existing thing: forEach()

I'll give you a quick rundown of each, followed by examples using the older, non-arrow-function syntax as well as the newer arrow-function syntax.

Return one new entry for every existing entry: `map()`

If you have an array of values, and you want to do something to each entry in that array and return a new array with the new values, then map() is your friend. Here's a simple function that takes an array and doubles every entry:

const originalArray = [1, 2, 3];
const newArray = originalArray.map(function(item) {
  return item * 2;
});
console.log(newArray); // -> [2, 4, 6]

Here's the same thing using the newer syntax:

const originalArray = [1, 2, 3];
const newArray = originalArray.map(item => item * 2);
console.log(newArray); // -> [2, 4, 6]

Notice that, with the newer arrow syntax, we don't have to use the function keyword, the return keyword, or curly brackets. That's because arrow functions give us an implicit return for 'simple' functions like this one. You can read more about arrow functions here, from Wes Bos.

Return a new array with only some of the existing entries: `filter()`

Filter is probably the easiest array function to understand, because it is so well-named. Filter takes an array of values, performs a function or comparison on each value, and then returns a new array of just the values that pass it's test (what we call 'truthy' values).

Here's an example that takes an array of numbers and returns just the ones that are larger than 5:

const originalArray = [1, 9, 4, 2, 42];
const newArray = originalArray.filter(function(item) {
  return item > 5;
});
console.log(newArray); // -> [9, 42]

Here's the filter part with an arrow function:

const newArray = originalArray.filter(item => item > 5);

Return one new thing only: `reduce()`

Sometimes you have an array of values and just want to return one new thing from them. Reduce takes an array, performs a function or comparison on each item, and then does something to what's called an 'accumulator'. This is one of those functions that's actually easier to describe with an example, because the terms one has to use to describe it are just as confusing as the function itself!

Suppose you have an array of names, and you want to count the number of times the name 'Bob' shows up:

const originalArray = ["Alice", "Bob", "Charlie", "Bob", "Bob", "Charlie"];
const numberOfBobs = originalArray.reduce(function(accumulator, item) {
  if (item === "Bob") {
    return accumulator + 1;
  } else {
    return accumulator;
  }
}, 0);
console.log(numberOfBobs); // -> 3

Again with arrows:

const numberOfBobs = originalArray.reduce((accumulator, item) => {
  if (item === "Bob") {
    return accumulator + 1;
  } else {
    return accumulator;
  }
}, 0);

As you can see, the arrow function didn't save us as much typing this time, because we had to provide two parameters to the function and then had logic before we could return, so we still needed curly brackets.

The 0 at the end of the reduce function is the value we start off the accumulator with, adding 1 to it if the value we encounter is "Bob", otherwise we return the accumulator as it currently is. If you don't return anything, then the next time the function is run the accumulator will be undefined.

Do something with each array value but don't return anything: `forEach()`

Sometimes you'll have an array of values that you want to do something with, but don't need to keep track of what the return is from each function call. This is what forEach() is for.

const originalArray = [1, 2, 3];
originalArray.forEach(function(item) {
  doSomething(item);
});

And again with arrows:

originalArray.forEach( item => doSomething(item); );

Final Notes

Simple and sweet. These are the simplest use cases I could come up with for each function to try and make it as easy as possible to understand when you should use each. There is a huge amount of tasks you can do with these functions, and there is an 'advanced' form of each of these functions that gives you the current index too:

arr.map((item, index) => {})
arr.filter((item, index) => {})
arr.reduce((accumulator, item, index) => {})
arr.forEach((item, index) => {})

If you need it, use it!

My Favorite Git Helpers

Andrew Steele — Thu, 08 Jun 2017 15:47:31 +0000

You can find all of these aliases and functions (and then some!) on my Github here:Â https://github.com/Andrew565/dotfiles. Read on for detailed explanations of what they are and what they do, and be sure to also check out my preferred git workflow.

I use bash in my terminal. I know ZSH and fish and all the rest have their niceties, but I started with bash, and I like it fine enough, so that's what I use.

My favorite thing to do in bash? Create aliases and helper functions for everything, especially Git commands. So, here's a list of some of my favs.

Bash Aliases

# Git Aliases
alias g="git"
alias gs="git status"
alias gl="git log"
alias grh="git reset --hard"
alias gcmm="git checkout --"
alias gsm="git stash && git co master && git stash pop"
alias gsd="git stash && git co development"
alias gmd="git merge development"
alias gmm="git merge master"
alias gupdate="git co development && git pull"
alias glatest="git co development && git pull"
alias gmupdate="git co master && git pull"
alias gcm="gmupdate"
alias gphm="git push heroku master"

Most of these are probably self-explanatory. Here are a couple commands that may not be immediately obvious:

alias gsm="git stash && git co master && git stash pop"

This is invaluable when I do work inÂ a feature branch that I actually wanted in the master branch. This doesn't happen as much anymore since most of the time I never commit directly to master, but it happens.

alias gcmm="git checkout --"

This command is when you have a fileÂ staged for commit and you don't actually want it to be part of the current commit. It could also be aliased as 'unstage'.

Bash Functions

Aliases will only get you so far. Sometimes you want to be able to bundle function calls together, or use variables. That's where bash functions come in.

gnew - Create aÂ new branch

# create new branch from a default named branch
# modify the first line to make it an argument if desired
gnew() {
 DEST_BRANCH=$2
 : ${DEST_BRANCH:='master'}
 git co $DEST_BRANCH
 git pull
 git co -b "$1"
 # bundle install # If using Bundler (ruby)
 # bundle exec rake db:migrate
 git push -u
}

As it says, this creates a new branch based off of another branch. If you don't specify which branch to branch off of, it assumes/defaults to the 'master' branch. Use like this:

gnew new-branch-name old-branch-name

It then checks out the old branch/master, pulls to make sure you're branching off of the latest revision, then creates a new branch using the name you provided as the first argument. Commented out are commands to run bundler and rake db:migrate, only useful if you're working on a Ruby/Rails project. Finally, it does git push -u, which pushes up the new branch and sets up the local branch to track the remote version, which makes future push and pull commands more seamless.

grmÂ - Git Rebase Master

# Get the latest changes on master pulled down locally
# and then rebase them into/onto the current branch
grm() {
  CURRENT=`git rev-parse --abbrev-ref HEAD` # figures out the current branch
  git checkout master
  git pull
  git checkout $CURRENT
  git rebase master
}

In my preferred workflow I always rebase the latest commits from master into my feature branch before I commit it. This keeps merge conflicts to a minimum and helps to keep the commit history clean.

gsrm - Git Stash && Rebase Master

# Stash current, then update to latest, then pop the stash
gsrm() {
  git stash
  grm
  git stash pop
}

Similar to grmÂ (and it even makes use of grm), this stashes whatever you're currently working that hasn't been staged/committed yet, then does the rebase, and then pops it out again. SUPER USEFUL if you know of upstream changes that you want to bring into your feature branch but what you're working on isn't ready to be committed. Side Note: don't use this as an excuse NOT to commit often. You should definitely still do that.

gswitch - Quickly checkout branches

gswitch() {
  BRANCH=`git branch | grep "$1"`
  git checkout $BRANCH
}

Switch branches by issue number or feature keyword. For example:

gswitch 1808 == git checkout features/1808-click-on-avatar

NOTE: only works well if you use a unique description, thus the recommendation to use issue numbers. Also works best if you delete your already-merged local branches regularly.

.gitconfig

If you're not taking advantage of a global .gitconfigÂ file, you're doing Git wrong. Here too I have a bunch of aliases, and a couple functions.

aliases - Lookup what aliases you have

aliases = !git config --get-regexp 'alias.*' | colrm 1 6 | sed 's/[ ]/ = /'

I so need to recreate this in bash, I have a hard time remembering all of the aliases I've created (there are a lot of them). ðŸ˜

cam - Commit while Adding files and attach a Message

cam = commit -am

This is (essentially) the same as:

git add . && git commit -m "your message"

Be careful that you don't use this if you have any unstaged files you don't want to be committed, as it will add everything to the commit.

last - What is the last thing I committed?

last = cat-file commit HEAD

co - Checkout

co = checkout

delete-local - Clear out old branches quicker

delete-local = branch -d

Somehow it's easier for me to remember git delete-localÂ than git branch -d.

delete-remote - Clear out remote branches quicker

delete-remote = "!sh -c 'git push origin :$1' -"

CAUTION: This doesn't ask if you know what you're doing before you do it, so be careful!

branches - Get a list of all of your local branches

branches = "!sh -c 'git branch -a | grep -v remotes'"

You can get rid of the grep -v remotesÂ if you want a list of remote branches too. This is another alias for 'natural language' purposes, just feels better to type git branches.

edit-unmerged & add-unmerged - Fix merge conflicts like a boss

# use like `git edit-unmerged; ...edit..., ...test...
# git add-unmerged; get commit || rebase --continue
edit-unmerged = "!f() { git diff --name-status --diff-filter=U | cut -f2 ; }; code `f`"
add-unmerged = "!f() { git diff --name-status --diff-filter=U | cut -f2 ; }; git add `f`"

This saves me so much time it's ridiculous. Basically, edit-unmerged looks at all of your files that are marked as "unmerged", meaning they have conflicts that need to be resolved. Then it opens them up in your code editor (replace codeÂ above with the cli alias for your preferred editor, vi, emacs, subl, etc.). When you're done, add-unmergedÂ finds that list of unmerged files again and does git addÂ on them (and only them, so you don't have to worry what else might get added). At this point, everything should be staged, so you can run git commitÂ or git rebase --continue.

Final Notes

Remember that a good craftsman never blames his tools. These helpers are not intended to be substitutes for actually knowing what you're doing. ðŸ˜‰ Here again is a link to my Github repo with these files:Â https://github.com/Andrew565/dotfiles.

How to Git Well

Andrew Steele — Thu, 08 Jun 2017 15:27:16 +0000

Throw a rock in any general direction, and you will hit yet another Git workflow. This one is mine, based on working with Git for 10+ years now. It makes use of git rebase, so turn away now if you're scared of rebasing (and then go read this and realize that it's nothing more than another tool). BONUS: be sure to check out my handy git helpers too!

Find your origin repo
Fork the origin repo to create your own repo
- If using Bitbucket, it will automatically set up your repo to sync with origin unless you uncheck 'keep in sync'
Clone your fork to your local machine, where origin will refer to your fork.
Create a feature branch off of your local master
- git checkout –b feature-branch-name replacing "feature-branch-name" with whatever name you want to give your branch
- Good practice: make your branch names unique and specific to the task or feature you're working on. branch-1 is not a useful branch name, time-travel-feature is better, adding-unlimited-undo-in-cms is best.
- Optional: push the new, empty feature branch to your fork’s remote endpoint using git push –u origin feature-branch-name. This sets up 'tracking' so that every time you push going forward you don’t have to specify where, you do a git push and it will already know where to push to. Same with git pull.
DO YOUR WORK
- Commit early and often. I recommend committing every time you get something to 'done' or at least working, but make a WIP (work in progress) commit anytime you need to switch tasks or want a waypoint for what you’re working on.
Make a 'final' commit, if you haven’t already.
Rebase your feature onto the current version of master (this reduces merge conflicts)
- git rebase origin/master
- git rebase -i origin/master if you want to get fancy and pick and choose commits interactively
Fix any merge conflicts, if any.
- FIX, FIX some more, FIX again
- git add . or git add /file(s)/that/were/changed
- git rebase -–continue
Having resolved any conflicts, push up your feature branch again, forcing your remote to overwrite whatever is already there (because rebasing will change the branch’s history and thus change its SHA checksum).
- git push –f
Create a pull request from your feature branch back up to the original origin repo's master branch.
- i.e. fork/feature-branch-name -> origin/master
Rest, reflect on what you have accomplished, and then start over again from step 4.

Here is what the cycle looks like:

OriginMaster -> ForkMaster -> LocalMaster -> LocalFeatureBranch -> ForkFeatureBranch -> OriginMaster

Bitbucket will auto-sync OriginMaster and your ForkMaster if you're using Bitbucket. Then you have to pull down any updates from ForkMaster to your LocalMaster. Then, you switch to your LocalFeatureBranch and rebase it onto the latest changes in LocalMaster. Then you push up to ForkFeatureBranch, where you create a Pull Request from there to the OriginMaster, and the cycle starts over again.

Good practice: any time you there is a merge of a significant amount into the 'origin' repo’s master branch, it’s a good idea to update your local master and rebase your feature branch. The more you keep your feature branch up-to-date with the latest changes, the easier merge conflicts will be to solve, and the fewer surprises you will have to deal with as you work.

If you haven't checked it out yet, go here for my handy git helpers that make this workflow super easy, fast, and intuitive (from the command line).

Making a Card Game in JS, pt. 2 - The Surprises

Andrew Steele — Thu, 11 May 2017 20:02:20 +0000

This is the second part of my series on creating a card game based on Dungeon Solitaire by Matthew Lowes. You can find the first part of this series here.

The Surprises

Since my first post in this series, I ran into a very strange occurrence of events which led to the setup I had been working with falling apart to the point that I could no longer use it. As such, this post is going to focus briefly on some of the backend infrastructure changes I've made along the way.

In the Beginning, there was a Glitch, and it was Good

From the very beginning, I had envisioned this game being a Single-Page Application (SPA). There's nothing about this game that will require being backed by a database, nor is there any calculation so complex it can't be handled by the front-end. Knowing these things, I decided to start this app in Glitch, an online IDE of sorts that allows you to code in the browser. While there are many things that make Glitch awesome, what I like best is the live-reloading combined with auto-save, so you instantly get an online, up-to-date app that you can test as soon as you write a line of code. (Remixing someone else's app so you don't have to do all of the boilerplate yourself is also really really nice.)

This was a fine setup until I ran into two issues which have more to do with me than they do with Glitch itself. The first was intermittent saving issues due to a spotty internet connection. Word to the wise: never do anythingÂ critical online over public Wi-Fi (looking at you Panera). This was tolerable until the time I lost 20+ minutes worth of work to it.

The second issue was ES6/ES2015 support. I wanted this app to be as cutting-edge as plain JS can get, soÂ I wanted to make use of all of the bells and whistles of ES2015. Glitch's built-in ES2015 support is limited to whatever Node supports, which meant that while most things worked, I couldn't make use of import or export statements to make my classes modular (this was way back in the time before Node added module support). While there are workarounds to this, I decided if I was going to go to all that trouble I would probably be happier just running it all locally.

CodeKit is It - Until I Break It

My favorite tool for running local projects is CodeKit. It's one of the easiest-to-use tools for handling all of the finicky backend server stuff and preprocessors that are annoying to configure and set up. Think of it like a GUI version of Grunt or Gulp. Usually, it works great. But because I can't leave well enough alone, I tried to mess with one too many settings while trying to get the import/export keywords to work and ended up breaking something bad enough that I couldn't get it to work anymore. Again, I'm sure this is another PEBKAC error, but I decided again that if I'm going to go to all of the trouble to try and fix what I did, I might as well bite the bullet and start over entirely with a hand-coded task-runner setup.

A More Modern Setup

Because I almost never start things from scratch well, I decided to look up tutorials on what others recommend. I found this article from Gina TrapaniÂ whichÂ echoed a lot of frustrations us web devs have over the moving-target which is JS development these days. That article led to this extensive guideÂ fromÂ Jonathan Verrecchia (works at Yelp), which I followed as closely as I could.

The one step that blew me away was enabling Airbnb's styleguide on my code via ESLint. I consider myself a pretty goodÂ developer, soÂ I was shocked by how much sloppiness I had in my code.

All's Well That Ends...

Okay, so now I'm back on track. NEXT time I'll get back to the actual code at hand!

How to Make a Card Game in JavaScript, part 1

Andrew Steele — Fri, 17 Mar 2017 15:09:13 +0000

I've been playing this solitaire card game for awhile now called Dungeon Solitaire - Tomb of the Four Kings by Matthew Lowes. The game simulates deep-diving into a tomb searching for the treasures buried there along with four kings. What I've always loved about this patience-style game is that it has simple-to-learn rules, uses a standard deck of cards so it can be played anywhere, and yet brings a rich story element to what would otherwise be ‘just another solitaire game'.

THE SETUP

I made the choice early on to create this game using plain, pure, vanilla JavaScript. I'm a front-end engineer by trade, so I figure making this game in plain JS would give me the broadest appeal to potential employers. I've used and liked Ember and React, and I've even tried Angular, but I have always felt MVC frameworks often are overkill for most applications.

The first iteration of this game is going to be text-based, with few or no graphics. A proof-of-concept. One of the first things I did was create a helper for DOM manipulation:

function getById(_id) {
  return document.getElementById(_id)
}

I could have made an alias to document.querySelectorAll(), but my general preference is to use IDs for JavaScript hooks, so if I know I'm going to have a unique ID for the majority of actions, then there's no reason not to use getElementById.

The first object type I created was a Card object since this is a card game. JavaScript prior to ES6/ES2015 didn't have a real ‘class' system, so my first instinct was to create a plain object, especially since the Card object was going to be a very simple one. Here's how it looked at first:

var Card = function(data) {
  this.rank = data.rank;
  this.suit = data.suit;
  this.value = data.value;
  this.name = this.rank + " of " + this.suit;
}

Card.prototype.listItem = function() {
  var el = document.createElement('li');
  el.innerText = this.name;
  return el;
}

This would have been fine, of course, but as I refactored some things as I went I reconfigured it into a class. Here's what it looks like now:

class Card {
  constructor(data) {
    this.rank = data.rank
    this.value = data.value
    this.suit = data.suit
    this.name = this.rank + " of " + this.suit
    this.graphic = '' // TODO
  }

  listItem() {
    var el = document.createElement('li')
    el.innerText = this.name
    return el
  }
}

As you can see, not very different, but the class syntax does make some of it a little bit simpler to read. Also, I dropped the semicolons at the end of every line; again, for readability.

The second thing I added was a listItem() method. This gives me a quick and easy way to display this card in the DOM, similar to the convenience property for Card.name. The class syntax here is interpreted by the browser the same as adding the function via the prototype chain, but it's a little bit cleaner to read.

That's it for this post. Next time, I'll start looking at the Game and Level objects, as well as give you a look into the HTML structure of the app.

DEV Community: Andrew Steele

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

hafcaf - The No-Framework SPA Solution for Everyone

How the Magic Happens

A Little JavaScript Goes a Long Way

What else?!?

Which Array Function When?

Short version

Return one new entry for every existing entry: map()

Return a new array with only some of the existing entries: filter()

Return one new thing only: reduce()

Do something with each array value but don't return anything: forEach()

Final Notes

My Favorite Git Helpers

Bash Aliases

Bash Functions

gnew - Create aÂ new branch

grmÂ - Git Rebase Master

gsrm - Git Stash && Rebase Master

gswitch - Quickly checkout branches

.gitconfig

aliases - Lookup what aliases you have

cam - Commit while Adding files and attach a Message

last - What is the last thing I committed?

co - Checkout

delete-local - Clear out old branches quicker

delete-remote - Clear out remote branches quicker

branches - Get a list of all of your local branches

edit-unmerged & add-unmerged - Fix merge conflicts like a boss

Final Notes

How to Git Well

Making a Card Game in JS, pt. 2 - The Surprises

The Surprises

In the Beginning, there was a Glitch, and it was Good

CodeKit is It - Until I Break It

A More Modern Setup

All's Well That Ends...

How to Make a Card Game in JavaScript, part 1

THE SETUP

Return one new entry for every existing entry: `map()`

Return a new array with only some of the existing entries: `filter()`

Return one new thing only: `reduce()`

Do something with each array value but don't return anything: `forEach()`