Forem: Joe Boris

Practical Code Architecture 🛠️ for Beginners (in JavaScript)

Joe Boris — Tue, 30 Apr 2024 15:36:10 +0000

There are many ways to accomplish the same thing in programming. Code architecture is basically the study of "which way is better".

Note: In this article, "better" means code that's generally considered easier to read, scale, and maintain.

What's in this article?

This article will briefly introduce three major code architecture subjects, and explain how I've found them helpful in my 10+ years of experience as a full-stack JavaScript developer. This is intended to be a simple and practical introduction, rather than comprehensive and technical.

Subjects:

Paradigms
Principles
Patterns

Paradigms 🏛️

Paradigms are generally the broadest and (in my opinion) most important subject. They're sort of like "styles" to write code in. In my experience, the ones most relevant to web development are declarative/imperative code, Reactive Programming, and Functional Programming.

Declarative/Imperative Code

Declarative code is code that combines more work into fewer statements/expressions, while imperative is the opposite.

More Imperative

let x = 0;

...

if(something){
  x = 5;
}

...

return x;

More Declarative

const x = something ? 5 : 0;

...

return x;

In general, more declarative code is considered better. In the above examples, imagine if each ... were 100 lines of code. It would be much harder to figure out what value is returned in the imperative example.

Reactive Programming

Reactive Programming is about writing code to automatically trigger operations in response to data changing.

Imagine you're making the shopping cart page of a shopping app. The cart has an underlying source of data we'll call items. Imagine you have a requirement to navigate back to the homepage as soon as there are no items left in the cart.

One Approach

let items = [];

function onRemoveButtonClicked(item) {
  items = ...;
  if(items.length == 0){
    navigateHome();
  }
}

function onClearButtonClicked() {
  items = ...;
  if(items.length == 0){
    navigateHome();
  }
}

But what should really trigger the navigation? Clicking "Remove Item"? Clicking "Clear Items"? The true answer is "changing the data in items".

More Reactive

let items = [];

function setItems(newItems){
  items = newItems;
  if(items.length == 0){
    navigateHome();
  }
}

function onRemoveButtonClicked(item) {
  setItems(...);
}

function onClearButtonClicked() {
  setItems(...);
}

A more reactive approach could be to use setItems in place of items = .... That way, "changing the data in items" will trigger the navigation whenever appropriate.

Fun Fact: This paradigm is where React.js gets its name!

Functional Programming

Functional Programming is basically writing declarative code, among other things. One particularly helpful thing is "pure functions".

A function is "pure" if it...

Gets everything it needs from arguments only
Does not affect the outside world in any way

Note: Something that affects the outside world is called a "side effect"

Consider this example...

let z = 0;
console.log(sum(2, 2));
console.log(z);

It's very obvious what should happen. You should see 4, then 0 in the console. If sum is a pure function, then that result is guaranteed. But, imagine if sum was defined like this...

function sum(x, y){
  z = x + y;
  return x + y;
}

This example is "impure", because z = x + y affects the outside world. This makes the results less predictable and harder to keep track of, which tends to cause bugs.

Note: Not every function can be pure! UI event handlers, rendering functions, and back-end route handlers, for example, are rarely pure.

Principles 📜

Principles are less broad than Paradigms. They're sort of like rules to follow. The most popular Principles are the so-called SOLID principles.

S - Single Responsibility Principle
O - Open-closed Principle
L - Liskov Substitution Principle
I - Interface Segregation Principle
D - Dependency Inversion Principle

Although these principles were intended to apply specifically to object-oriented programming, they can easily be applied to any type of "module". Below are two principles that I've found particularly helpful...

Note: "Module" is a vague term in this field of study meaning a piece of code like a function, UI component, API route, file, etc. In JavaScript, "module" can also specifically mean a file that imports/exports things.

Single Responsibility Principle

The Single Responsibility Principle says that a module should have only one responsibility.

❌ Single Responsibility

const [area, volume] = getAreaAndVolume(shape);

✔️ Single Responsibility

const area = getArea(shape);
const volume = getVolume(shape);

In the above example, getAreaAndVolume clearly has more than one responsibility.

Dependency Inversion Principle

The Dependency Inversion Principle says that a module should only depend on generic "interfaces" provided by other modules, not specific details.

Note: "Interface" is another vague term which roughly means "the way to use" a module. In other programming languages, "interface" can also have a similar, but more specific meaning.

Imagine you're making a UI component that needs to save some data, but you don't know or care how the data should be saved yet. Maybe data storage is your co-worker's responsibility, or maybe you just want to worry about it later. In either case, you could make a data storage module and follow the Dependency Inversion Principle.

❌ Dependency Inversion

import { saveDataInLocalStorage } from "../data-store.js";

...

saveDataInLocalStorage(data);

✔️ Dependency Inversion

import { saveData } from "../data-store.js";

...

saveData(data);

In the above example, saveDataInLocalStorage is more specific than necessary. All we care about in the UI code is that we need to save data. We don't care about the details yet.

Patterns 📦

Patterns are even less broad than Principles. They're sort of like recipes you can use in your code. There's one pattern I've found particularly useful.

Unidirectional Data Flow

Unidirectional Data Flow can be implemented by rendering a UI simply as a reflection of the current state/data of the app.

❌ Unidirectional Data Flow

let items = [];

function onAddButtonClicked(item) {
  items = ...;
  document.querySelector("#item-list").innerHTML += `
    <div>${item.name}</div>
  `;
}

function onClearButtonClicked() {
  items = ...;
  document.querySelector("#item-list").innerHTML = ``;
}

✔️ Unidirectional Data Flow

let items = [];

function onAddButtonClicked(item) {
  items = ...;
  renderItems(items);
}

function onClearButtonClicked() {
  items = ...;
  renderItems(items);
}

In the above example, imagine the function renderItems just renders the current state of items at any time. Instead of updating individual parts of the UI depending on the situation, we can just call renderItems whenever items changes.

Conclusion

There's MUCH more to learn about code architecture out there. These are just a few concepts that I eventually learned throughout the years (sometimes the hard way). Hopefully this helps demystify the subject for others as well.

💬 Feedback and questions are welcome below 👇

Code Usability (DX) and my "Ease of Use" Levels

Joe Boris — Thu, 29 Jun 2023 19:29:33 +0000

Let's talk about a topic under the subject of DX that I call "code usability". When you create an API for a module, its usability can have a huge impact on productivity. I identified what makes code easy for me to use and came up with my 3 "ease of use" levels.

In the following JavaScript examples, imagine we're using a geometry library, and we want some way to represent a pyramid shape in our code.

Level 1: Easy to use

You can easily figure out how to use it by reading documentation or examples.

✔️ Simple
✔️ Well-documented

Example:

Level 2: Intuitive to use

You can guess how to use it without reading documentation, usually based on function, class, or variable names.

✔️ Good naming

Example:

Level 3: "Uses itself"

You can use it without even thinking about it, usually with code assist (Intellisense). It also prevents you from misusing it by mistake.

✔️ Facilitates code assist
✔️ Thorough type checking and error handling

Example:

Takeaway

Unfortunately, the APIs we use don't always reach level 3. Try using a library with lackluster documentation, or a web service that responds with vague error messages, and it can cost you hours. So, how can you write usable code? Well in JavaScript, for example, you can get pretty far with good JSDoc comments.

Example:

/**
 * Returns an object representing a pyramid with the given dimensions.
 * @param {number} length
 * @param {number} width
 * @param {number} height
 * @returns {{length: number, width: number, height: number, volume: () => number}}
 * @example
 * const p = createPyramid(2, 3, 4)
 * const v = p.volume()
 */
export function createPyramid(length, width, height) {
  return {
    length,
    width,
    height,
    volume() {
      return (length * width * height) / 3;
    },
  };
}

The rest comes down to your design decisions. Try putting yourself in the shoes of the consumer, and test if your code reaches level 3. You may be surprised how much you can help the future consumer... even if it ends up being YOU.

💬 Feedback/criticism are welcome below 👇

Simple JS UI Components

Joe Boris — Fri, 19 Nov 2021 11:30:35 +0000

The Web Component APIs in JavaScript are great, but they're relatively new and kinda hard to learn. They're also struggling to gain traction in the industry still (at the time of writing), making them a little risky to invest in. In the meantime, there are simple patterns you can follow to make components in vanilla JavaScript without the Web Component APIs.

First, let's establish a more declarative way to create a DOM node. You can use a library like jQuery, or define a function to do it yourself. In this article let's use our own function called $.

// Return a DOM element created from parsing the HTML string
function $(html, properties = {}) {
  const template = document.createElement("template");
  template.innerHTML = html.trim();
  const element = template.content.firstChild;

  // Copy the properties to the element
  Object.assign(element, properties);

  return element;
}

Usage:

const form = $(`<form></form>`);

Now let's make a little component. Let's say we want a generic CRUD form component...

function newCrudForm(data, mode) {
  const form = $(`<form></form>`);

  render(mode);

  function render(mode) {
    form.innerHTML = "";

    const disabledInRead = mode == "read" ? "disabled" : "";

    form.append(
      $(`<label>Text: </label>`),
      $(`<input type="text" ${disabledInRead} />`, {
        value: data.text,
        // NOTE: Using this method syntax will bind 'this' to the textbox
        oninput() {
          data.text = this.value;
        },
      }),
      $(`<button>${mode == "read" ? "Edit" : "Save"}</button>`, {
        onclick() {
          const newMode = mode == "read" ? "update" : "read";
          render(newMode);
        },
      })
    );
  }

  return form;
}

Note: For simplicity, I didn't implement two-way binding, but it can be added to $ easily

Usage:

const data = { text: "example text" };
document.body.append(newCrudForm(data, "read"));

Explanation

newCrudForm returns a form element with its own "state". Its state consists of the data object and the mode string. The data state is bound to the textbox. To change the mode state and react to the change, we just need to re-render and pass in a new value. That's what the button does.

Note: "state" is just the info associated with a component

Conclusion

Hopefully you'll find this easier to learn than the Web Component APIs like I did. Thoughts? Questions? Criticism? Leave a comment below 👇

The "Best" Raw JS Approach to the DOM

Joe Boris — Wed, 17 Nov 2021 17:00:46 +0000

TL;DR: Create your elements entirely with JavaScript, rather than hard-coding in your HTML file.

Odds are, interacting with the DOM is the most common thing you'll use JavaScript for on the front-end. There are frameworks and libraries to facilitate this, but sometimes they aren't an option. In this article, I'll demonstrate the best vanilla JS approach to the DOM in my experience. I'll show a naïve approach, then a simple demonstration of another approach. The target audience of this article is intermediate-level developers, but I encourage beginners to take this approach, too.

Disclaimer: "Best" is just my opinion. I welcome criticism, feedback, or questions in the comments.

Introduction

Let's say you have some data - a list of 5 objects representing products, each with a name, price, and description. Your web app needs to 1) render them, and 2) update them.

Note: to "render" means to display on the page

Naïve approach

A naïve approach would be to hard-code lots of HTML, use JS to search for certain elements, then add the data and event handlers to those elements.

<form class="product">
    <input class="name" type="text"/>
    <input class="price" type="number"/>
    <input class="description" type="number"/>
    <button>Edit</button>
</form>

<!-- Repeat 4 more times... -->

const products = [
  // 5 product objects...
];

const forms = document.querySelectorAll(".product");

for (let i = 0; i < forms.length; i++) {
  const nameTxt = forms[i].querySelector(".name");
  const priceTxt = forms[i].querySelector(".price");
  const descriptionTxt = forms[i].querySelector(".description");

  nameTxt.value = products[i].name;
  priceTxt.value = products[i].price;
  descriptionTxt.value = products[i].description;

  forms[i].onsubmit = (e) => {
    e.preventDefault();
    products[i].name = nameTxt.value;
    products[i].price = priceTxt.value;
    products[i].description = descriptionTxt.value;
  };
}

This is the approach that every beginner tutorial teaches. Sometimes it's sufficient, other times not. Its flaws eventually become problematic, and I found myself addressing them over and over until I took a different approach.

Flaws

❌ Could be done with less code
It's hard to tell as a beginner, but this is very important. It could also be done without repeating code (i.e. the HTML).
❌ No data binding
What if you update a product's name somewhere else in your code? The page will still display the old name. This could cause problems.
Note: to "bind" data means to sync data with the UI. In other words, the user typing in the textbox will immediately update the data, and vice versa.
❌ Not reusable
What if you need to render/update a product again on another page? It would take a bit of work to make this code easily reusable.
❌ Naming things is hard
Spending time thinking of the best class and variable names? This approach necessitates that chore.
❌ Tight coupling
Struggling to remember the class names from your HTML file? Spending time adapting your JS to work on another page? This approach tightly couples your JS and HTML, worsening these problems.
Note: tightly coupled code is 2+ pieces of code that are highly dependent on each other to work.

"Best" approach

<div id="product-section"></div>

const products = [
  // 5 product objects...
];

function newProductList(products) {
  const list = newElement(`<div></div>`);

  for (let product of products) {
    list.append(newProductForm(product));
  }

  return list;
}

function newProductForm(product) {
  const form = newElement(`<form></form>`);
  form.append(
    newElement(`<input type="text" name="name" />`, { boundTo: product }),
    newElement(`<input type="number" name="price" />`, { boundTo: product }),
    newElement(`<input type="text" name="description" />`, { boundTo: product })
  );

  return form;
}

function newElement(html, options = {}) {
  const template = document.createElement("template");
  template.innerHTML = html.trim();
  const element = template.content.firstChild;

  if (options.boundTo) {
    const object = options.boundTo;
    element.value = object[element.name];
    element.oninput = () => {
      object[element.name] = element.value;
    };
  }

  return element;
}

// Only occurrence of HTML <-> JS coupling
const productSection = document.querySelector("#product-section");
productSection.append(newProductList(products));

This approach may be harder to understand at first, but it's worth the investment. Aside from the convenience of newElement, the main point is to identify elements that are coupled to your data, and make them "components" that are created entirely with JS.

Explanation

newElement is our function, which takes in an HTML string as an argument and returns a DOM object created from it (info). It can also take in an object as a second, optional, argument. The object can have a property called boundTo that's assumed to be an object itself. The function assumes the boundTo object has a property of the same name as the name attribute of the element, and binds that property to the element. For example...

newElement(`<input type="text" name="price" />`, { boundTo: product })

...binds the product's price property to the textbox.

Note: It's safe to use the name attribute this way, because its traditional purpose is to be the "key" associated with the textbox's value.

Benefits

✔️ Less code
This approach takes less total code, has little repeating code, and automatically scales with the number of products in the array.
✔️ Data binding
This approach updates the products as the user types.
Note: for simplicity, I only demonstrated one-way binding. Two way binding can be added to newElement easily.
✔️ Reusable components
This approach turns the product list and product form into easily reusable components.
✔️ Less naming involved
This approach eliminates the need for classes entirely, and makes some of the temporary middleman variables less necessary.
✔️ Loose coupling
The HTML and JS in this approach are much less interdependent. The JS no longer depends on the HTML having tags with so many classes ("product", "name", "price", and "description"). This makes the JS more easily reusable, among other things.

Conclusion

I faced the problems with the first approach countless times, and ended up patching them different ways every time. I realized this was taking so long that I would actually save time by investing in this approach when I started the project. Now I do it any time I can't use a framework.

Note that the example is simplified for demonstration. You could improve on it with, for example, two-way binding in newElement, handling other input types in newElement, more "state" parameters and a nested render function inside your components, etc...