DEV Community: How to dev

Advantages of unit testing—with examples in Jasmine

Marcin Wosinek — Thu, 15 Feb 2024 21:50:48 +0000

Writing unit tests takes time and effort. Nonetheless, many teams insist on writing them anyway—that’s because of the benefits they bring to a project. Those benefits are mainly the following:

fast feedback—unit tests speed up each iteration of tweaking the code, and those gains can offset at least some time spent on writing tests.
Explicit expectations—clear communication of what is expected from the code.
Attention to edge cases—good unit tests will provide examples for every edge case that developers can think of.
Easy refactoring—an infrastructure to support code evolution in the long term.

Let’s see those benefits in more details:

Fast feedback

Computers excel at well-defined, repetitive tasks. When you write unit tests, you write code that will verify whether your program does what it was meant to do. With automated verification in place, you can check your code very quickly. In my work, I have 3200+ that run just under14 seconds. With such performance, you can retest your whole codebase every time when you save your code. After I got more experience with writing unit tests, it started to feel that the time I saved with the quicker feedback loop returns the time I invested in writing tests.

As an example, let’s see update unit tests for the translate method introduced in my last article:

  describe("translate", () => {
    it("should translate to supported languages", () => {
      expect(translate("hello", "en")).toEqual("Hello!");
      expect(translate("hello", "pl")).toEqual("Cześć!");
    });

    it("should default to english if language missing", () => {
      expect(translate("hello", "fr")).toEqual("Hello!");
    });

    it("should return the key if translation is missing", () => {
      expect(translate("farewell", "en")).toEqual("farewell");
      expect(translate("farewell", "pl")).toEqual("farewell");
      expect(translate("farewell", "fr")).toEqual("farewell");
    });
  });

Running those tests happens in the blink of an eye:

npm run test

> testing-example@1.0.0 test
> jasmine

Randomized with seed 31262
Started
...


Ran 3 of 21 specs
3 specs, 0 failures
Finished in 0.003 seconds
Incomplete: fit() or fdescribe() was found
Randomized with seed 31262 (jasmine --random=true --seed=31262

Explicit expectation

Another big advantage of unit tests is stating the expectations explicitly in the code. For example, the data formatting function shortDate could do one of the following things when provided with an argument that is not a date:

throw an error,
return undefined, or
return empty string.

Each of those choices could be a good idea in some places, so it could happen that at some point the exact behavior will be changed. I like adding special cases like this to the test, so the future developer will be reminded that some code can depend on specific behavior when they start changing the API.

shortDate tests, updated to cover invalid inputs:

  describe("shortDate", () => {
    it("should correctly format date", () => {
      const date = new Date("2023-11-02");
      expect(shortDate(date)).toEqual("2023-11-02");
    });

    it("should fail gracefully for no-dates", () => {
      expect(shortDate("")).toEqual("");
      expect(shortDate({})).toEqual("");
      expect(shortDate(1)).toEqual("");
      expect(shortDate()).toEqual("");
    });
  });

Attention to edge cases

When I write the implementation for a method, I think about the happy path—everything going as expected. When I write unit tests, I think about everything that can go wrong:

some arguments missing,
wrong data type, or
invalid combinations or arguments—such as dividing 0 by 0.

Covering those edge cases makes the tests really helpful. A few examples form the demo repository:

greet tests:

  describe("greet", () => {
    it("should greet by name and surname", () => {
      expect(greet("Lorem", "Ipsum")).toEqual("Hello Lorem Ipsum!");
    });

    it("should fail gracefully for missing arguments", () => {
      expect(greet("Lorem")).toEqual("Hello Lorem!");
      expect(greet(undefined, "Ipsum")).toEqual("Hello Ipsum!");
      expect(greet()).toEqual("Hello!");
    });
  });

applyDiscount tests:

  describe("applyDiscount", () => {
    it("should lower the price accordingly", () => {
      expect(applyDiscount(120, 25)).toEqual(90);
      expect(applyDiscount(8, 50)).toEqual(4);
    });

    it("should manage rounding error", () => {
      expect(applyDiscount(0.1, 40)).toEqual(0.06);
    });

    it("should round results to 0.01", () => {
      expect(applyDiscount(1.11, 25)).toEqual(0.83);
    });

    it("should return NaN for corrupt inputs", () => {
      expect(applyDiscount("", 40)).toBeNaN();
      expect(applyDiscount(40)).toBeNaN();
      expect(applyDiscount()).toBeNaN();
    });

    it("should throw errors on discount percentage outside 0-100 range", () => {
      expect(() => applyDiscount(120, 125)).toThrowError();
      expect(() => applyDiscount(120, -25)).toThrowError();
    });
  });

calculatePrice tests:

  describe("calculatePrice", () => {
    it("should find a price of many products", () => {
      expect(calculatePrice(4, 3)).toEqual(12);
      expect(calculatePrice(9, 0.5)).toEqual(4.5);
    });

    it("should manage rounding error", () => {
      expect(calculatePrice(0.1, 0.4)).toEqual(0.04);
    });

    it("should round results to 0.01", () => {
      expect(calculatePrice(1.11, 0.5)).toEqual(0.56);
    });

    it("should return NaN for corrupt inputs", () => {
      expect(calculatePrice("", 40)).toBeNaN();
      expect(calculatePrice(40)).toBeNaN();
      expect(calculatePrice()).toBeNaN();
    });
  });

Easy refactoring

Once I have all expectations for my code defined, it’s effortless to refactor it. We can safely reorganize the code, improving the quality while maintaining the behavior. Removing friction from code improvements is where we see plenty of long-term benefits from unit testing. When your team is enabled to improve code without the fear that they will break something, they are more likely to try improving things.

On the flip side, code that nobody can change without causing some unexpected changes is code that is very difficult and risky to improve. Unit tests are often a barrier that prevents code from entering into a spiral of growing complexity and unmaintainability.

ellipsis tests are a good example of checking all the behavior we could possibly care about:

  describe("ellipsis", () => {
    it("should shorten long text at 50 chars", () => {
      expect(
        ellipsis(
          "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque a faucibus massa."
        )
      ).toEqual("Lorem ipsum dolor sit amet, consectetur adipiscing…");
    });

    it("should leave short text unchanged", () => {
      expect(ellipsis("Lorem ipsum sin dolor")).toEqual(
        "Lorem ipsum sin dolor"
      );
    });

    it("should shorten to custom length", () => {
      expect(ellipsis("Lorem ipsum sin dolor", 10)).toEqual("Lorem ipsu…");
    });

    it("should return unchanged non-string argument", () => {
      expect(ellipsis(11)).toEqual(11);
      expect(ellipsis({ lorem: "ipsum" })).toEqual({ lorem: "ipsum" });
    });

    it("should ignore second argument if not number", () => {
      expect(
        ellipsis(
          "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque a faucibus massa.",
          {}
        )
      ).toEqual("Lorem ipsum dolor sit amet, consectetur adipiscing…");
    });
  });

Summary

The cost/benefit balance will depend a lot on the type of project and the team that works on it. For benefits to show, you need a certain quality of tests—and this can be difficult if nobody on your team has experience with building unit tests. The communication benefits are greater when you have a bigger team—so different people work on the code; or when the projects live a long time—so people need a reminder about their past decisions. Long-term benefits of enabled refactoring will appear only if the project exists long enough such that the need for refactoring has a chance to arise.

Pure functions and basic tests in Jasmine

Marcin Wosinek — Thu, 08 Feb 2024 08:49:07 +0000

Pure functions are the perfect case for unit testing. For a given input, we always expect the same output—there is no internal state involved. Let’s take a look at a few examples and some simple tests that check if the methods work as expected.

Jasmine

Jasmine is a unit test framework for JavaScript. It can run tests in both Node.js or on the browser. It’s used in the Angular framework, and it’s especially popular in projects based on Angular. It’s a solid choice for Vanilla JS projects, or projects based on other frameworks as well.

Happy path testing

Happy path testing is when we test a method with inputs that it’s expected to work normally using. The arguments are valid and within reasonable ranges. Those tests check if the method does its job correctly—the test cases should be straightforward examples of how the method is explained in its documentation.

Pseudocode examples:

expect(add(2, 2)).toBe(4),
expect(concatenate(“Lorem”, “Ipsum”)).toBe(“LoremIpsum”)

Those tests are meant to automatically catch it anytime the method key behavior is broken.

Methods

Let’s see a few simple methods: simple operations that we might need in some real-world application.

All implementations are greatly simplified—all methods will break in an ugly way if only we provide them with parameters that differ slightly from what is expected. The code is far from being robust.

greet

Method that greets the user with their name and surname:

export function greet(name, surname) {
  return `Hello ${name} ${surname}!`;
}

shortDate

shortDate is a formatting method that takes a date object and returns it formatted as a short string. The code:

export function shortDate(date) {
  return date.toISOString().substring(0, 10);
}

ellipsis

ellipsis takes a long text string and an optional length parameter and then trims the string to fit within the limit:

export function ellipsis(text, length = 50) {
  if (text.length > length) {
    return text.substring(0, length) + "…";
  }

  return text;
}

translate

A method that provides translated string values for a key and lang pair. It’s a simplified implementation of what could be replaced with more advanced translating libraries.

export function translate(key, lang = "en") {
  switch (lang) {
    case "en":
      switch (key) {
        case "hello":
          return "Hello!";
      }
    case "pl":
      switch (key) {
        case "hello":
          return "Cześć!";
      }
  }
}

applyDiscount

Method to apply a percentage discount to a price. It can feel like overkill with this naive implementation, but later when we start investigating edge cases it will get much more interesting.

export function applyDiscount(price, discountPercentage) {
  return price - (price * discountPercentage) / 100;
}

calculatePrice

This one calculates the total price when buying multiple units at a given price. It will also get more complicated after adding interesting edge cases.

export function calculatePrice(unitPrice, quantity) {
  return unitPrice * quantity;
}

Complete JS code

The complete JS code, src/main.js:

export function greet(name, surname) {
  return `Hello ${name} ${surname}!`;
}

export function shortDate(date) {
  return date.toISOString().substring(0, 10);
}

export function ellipsis(text, length = 50) {
  if (text.length > length) {
    return text.substring(0, length) + "…";
  }

  return text;
}

export function translate(key, lang = "en") {
  switch (lang) {
    case "en":
      switch (key) {
        case "hello":
          return "Hello!";
      }
    case "pl":
      switch (key) {
        case "hello":
          return "Cześć!";
      }
  }
}

export function applyDiscount(price, discountPercentage) {
  return price - (price * discountPercentage) / 100;
}

export function calculatePrice(unitPrice, quantity) {
  return unitPrice * quantity;
}

Adding Jasmine tests

To add Jasmine, let’s start by converting the folder into an npm package:

$ npm init -y
Wrote to …/package.json:
…

Then we can install the Jasmine package:

$ npm install --save-dev jasmine

added 42 packages, and audited 43 packages in 2s

13 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

then we can generate folders and files used by Jasmine:

$ npx jasmine init
(no output)

This command generates the following:

spec/—a folder where we can put *.spec.js files with the test, and
spec/support/jasmine.json—a file with the Jasmine config.

Unit tests

For the following unit tests, I’m focusing on the happy path only—I check if the result is as expected for reasonable inputs. The test should be self-explanatory, so let’s take a look at them:

import {
  greet,
  shortDate,
  ellipsis,
  translate,
  applyDiscount,
  calculatePrice,
} from "../src/main.js";

describe("main", () => {
  describe("greet", () => {
    it("should greet by name and surname", () => {
      expect(greet("Lorem", "Ipsum")).toEqual("Hello Lorem Ipsum!");
    });
  });

  describe("shortDate", () => {
    it("should format correclty date", () => {
      const date = new Date("2023-11-02");
      expect(shortDate(date)).toEqual("2023-11-02");
    });
  });

  describe("shortDate", () => {
    it("should shorten long text at 50 chars", () => {
      expect(
        ellipsis(
          "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque a faucibus massa."
        )
      ).toEqual("Lorem ipsum dolor sit amet, consectetur adipiscing…");
    });

    it("should leave short text unchanged", () => {
      expect(ellipsis("Lorem ipsum sin dolor")).toEqual(
        "Lorem ipsum sin dolor"
      );
    });

    it("should shorten to custom length", () => {
      expect(ellipsis("Lorem ipsum sin dolor", 10)).toEqual("Lorem ipsu…");
    });
  });

  describe("translate", () => {
    it("should translate to supported langauges", () => {
      expect(translate("hello", "en")).toEqual("Hello!");
      expect(translate("hello", "pl")).toEqual("Cześć!");
    });
  });

  describe("applyDiscount", () => {
    it("should lower the price accordingly", () => {
      expect(applyDiscount(120, 25)).toEqual(90);
      expect(applyDiscount(8, 50)).toEqual(4);
    });
  });

  describe("calculatePrice", () => {
    it("should find a price of many products", () => {
      expect(calculatePrice(4, 3)).toEqual(12);
      expect(calculatePrice(9, 0.5)).toEqual(4.5);
    });
  });
});

(file spec/main.spec.js)

Running tests

To run the tests, we can add the following script to package.json:

  ..
  "scripts": {
    "test": "jasmine"
  },
  …

With this in place, npm run test runs our tests:

$ npm run test

> testing-example@1.0.0 test
> jasmine

Randomized with seed 76873
Started
........


8 specs, 0 failures
Finished in 0.004 seconds
Randomized with seed 76873 (jasmine --random=true --seed=76873)

Summary

In this post, we took a look at a simple example of JS code and how it can be covered by unit tests. You can find the complete code example on GitHub.

How to prepare for a job interview

Marcin Wosinek — Thu, 01 Feb 2024 10:00:13 +0000

Let’s say you have a job interview in a few days. How should you prepare for it so that you can make an informed decision about joining the company, as well as make sure that your interests are taken care of?

Prepare your questions

An interview is a two-way street: it’s not only the company investigating you as a potential employee: in addition, you are investigating the company as a potential employer. Hopefully, you have some other options available—such as staying at your current place or trying out other companies interested in you. In the best case, you’ll have flexibility to decide whether you want to follow through with the company or not.

To learn about the potential employer, you need to ask questions. The question will depend on what’s important for you at the current stage of your career. Some things I would like to know before deciding to join a new company are as follows:

What is their development process? If they use some standardized methodology as Scrum, I would like to hear how they implement it. Especially whether they have Scrum Master and Product Owner roles covered—and whether those people are easily reachable. I would also ask if they do retrospectives meetings.
How do they do quality automatization: things such as unit tests, e2e, CI & code-style enforcing? For things that they don't have, I would ask if they would like to see it in the project.
I would ask about their product, and how they do product design/discovery.
Life–work balance questions inspired by Healthy Software Developer’s video: ** how long do employees usually work? ** how do they deal with emergencies? ** how often is there a need to receive a call or respond to messages outside working hours?

Salary negotiation

The point of going to the interview is to get to the salary negotiation. The result of the negotiation will have a great impact on your life for the whole time you spend at the company—it’s a smart move to prepare well. The earlier you start, the better—as you will have more time to investigate, ask questions, and plan your strategy.

The best resource for preparing for an interview in IT is Fearless Salary Negotiation. You can buy the complete e-book, read the chapters online, or get the key advice from the bite-size articles on the website.

Research compensation

Before you start negotiation, figure out the current situation at the market. A little bit of time spent on systematic investigation can give you a much more precise picture than anecdotes heard here or there. Check out this chapter on market value estimation.

Decide your minimum

Great advice is to decide on the minimum pay that you’ll accept before you start speaking with the company. It could happen that during the various rounds of interviews, they will manage to sell the company very well, or that the effort you have already invested into the company will make you more flexible than you should be. In those cases, having the minimum salary decided ahead of time can be very helpful. Relevant chapter from the book here.

Think open about your options

As you negotiate with the company, it’s good to be flexible about options you consider. If you are asking for more money than they have budget for, you can propose reduced hours with the same hourly rate that you are happy with. Similarly, commuting to the office can easily take 1–2 hours of your day, so a lower salary could be worth it if it comes with guaranteed remote work.

Practice interview

Try role-playing an interview with someone. If you can handle it, you can ask them to be tough on you—stricter than what you would expect from a real interview. Ideally, you’ll have a tough, low-stakes interview that would make you relaxed during the real thing.

Investigate the company

Learn about the company—all you can before the meeting, that is. Check their website, their LinkedIn page, and their key employees. Play around with their product if you can. In short, spend an hour or two trying to learn as much as you can about the company. It will help you ask important questions and make a good impression.

Summary

A bit of preparation can go a long way. As developers, we often think about the technical part of the interview, but learning about the company and preparing for salary negotiation can help us even more. We can filter out companies we shouldn’t join, and we can make sure that we get as good a deal as possible.

How to build a demo project

Marcin Wosinek — Thu, 25 Jan 2024 08:32:09 +0000

Creating example projects is a common way of showing your skills to potential employers. Let’s take a look at what’s important to keep in mind when building personal projects with an eye toward impressing prospective employers.

Simplicity

Building applications takes a lot of time and effort. Most projects of any kind are greatly underestimated. There are always unpredictable difficulties that you encounter only after you start working. Besides that, in the case of personal projects, the project will compete with all the other things that you could be spending your spare time on.

The solution to that problem is to keep the feature set as simple as possible. Even the simplest project proves your ability to deliver and shows how you work and what code you can create. If you can make the application solve some problem, that’s great—but focus on finding the minimal feature scope to address the need.

If you are looking for inspiration for an application to build, in my other article I present a simple energy usage calculator.

Covers many aspects

Keeping your feature set small will leave you with time and energy for expanding in another direction—to cover many different aspects of application development. Of all the types of things you can create, it’s always the first of its kind that delivers the most value. For example, demonstrating one class with full unit test coverage shows that you can design testable code, write unit tests, and set up the environment to run them. Writing ten classes would prove your persistence and commitment to the project, but there is a diminishing return on your investment.

Idea

First and foremost, you need an idea for your project. The scope constraints make it tricky to find something that is simultaneously interesting and simple. A common approach is to either make a simple clone of a known application or to follow somebody’s idea for a demo app.

A more creative approach would be to find a small real-world problem and try to solve it with an application. To keep the scope under control, you should aim for making a minimum viable product (MVP)—the simplest product that addresses the users’ needs.

The nice way to describe your application idea is to write user stories. You could start with a very high-level one:

As a gym user, I want an application to book training sessions.

Then you can move down to more precise ones:

As a gym user, I want to have a page that shows the gym schedule with available spots for each class. I want to be able to book classes that have spaces left.

Mockup

Before you begin in your code editor, it makes sense to draw the interface that you plan to build. You can catch many potential issues by thinking about how exactly things will be presented and how users will transition from one place to another. Working with pen and paper is much faster than working with code, and you can easily make many iterations of your interface in an hour or two.

You can use the mockups to communicate your ideas—as I wrote before.

Code repository

As you start working with code, it makes sense to start a new repository. Git is an important skill for all developers, and it’s worth showing that you are familiar with it and that you follow good practices. At the same time, putting your project on GitHub makes it accessible for others as well—so you show your skills and publish your work at the same time.

Communication

Communication skills are as important for programmers as technical skills. Your work has no way of impacting others if they cannot understand what your project is supposed to do. Usually, you demonstrate your communication skills in action to the people who interact directly with you. A demo project presents an excellent opportunity to demonstrate your skill to the broader public: the README file.

In the README file, your audience is clear: people interested in your project, most likely other programmers who have no idea about what it does and how it works. Providing this information efficiently will show that you can understand what users want to know and provide them just that. You can see more info about writing README files in a guest post on my blog.

Prototype

The next step would be to build a clickable interface. Build the screens that you designed with mockups using the technologies you plan to use in your final application. Don’t worry about implementing any functionalities: use hard-coded data and buttons that set values without any logic behind the updates. The goal is to give an impression of a usable application before spending time on building the actual thing.

The benefits of starting with a prototype are two-fold. You will be able to try out the interface or ask others to give it a shot. The feedback from this experience will inform your further work on the application—maybe you will tweak some screens, or you will realize you are missing something. Besides that, at this stage your project will be ready to share as a demo with others: there is not much code in there yet, but one will already be able to see enough of your work to evaluate your skills.

Code quality

With some code ready to go, I recommend you put some code quality checks in place. The most basic verification will be static analysis of your code—checking your code without executing it. A few things that you can set up for your code:

linters—Programs that check code for possible issues and recommend best practices. For frontend projects you can use things such as ESLint, Stylelint, HTMLHint
code style tools—Programs that enforce a specific formatting for your code. On the frontend, Prettier covers almost all file types you could expect. I already wrote about it on the blog

Vanilla JS

The next step is to implement the features with Vanilla JS alone. You can skip this step if you already know a JS framework well enough to build an application with it. If you don't, Vanilla JS is the safest bet—it’s the foundation that other solutions are using. I have a simple guide on how to set up a simple JS project with Webpack.

Continuous Integration

At this stage, your project will already have scripts:

static analysis to ensure the quality and styling of the code, and
a build script that prepares the code for deployment.

For each change set, you can expect the codebase to be able to pass both scripts without any errors. You can enforce this expectation by setting up continuous integration (CI). Git hosting providers such as GitHub and GitLab offer CI on even the free plans. You can read more about the benefits here.

Deployment

With CI in place, the very next step is to deploy your application somewhere. Deploying the application will make it easy for anybody to check out your application in action—after all, people are more likely to click on the link than to download and build code locally. The easiest places to deploy are GitHub Pages, or GitLab Pages—each of them is easy to set up from the repository hosting. For GitLab, I have a guide on the blog.

Framework

Finally, with all that in place, you can move your application to your framework of choice. There are many options available, and you should choose one that matches what you would like to learn and what’s needed in your job market.

If your application is indeed small, rewriting it to a framework shouldn’t be a big project—changing a few files from JS+HTML to whatever your frameworks uses. If it’s much more than that, you can rethink the scope of the project and find a smaller set of features to build your MVP. And build the rest after you move your project to the framework.

Testing

Lastly, to show that you care about the quality of the code you produce, you can add tests to the application. On the front end, we usually consider two levels of testing: unit tests that check the individual parts of the application, and end-to-end tests that interact with the whole app through its user interface. For a professional project, I recommend using both. For demo projects, unit tests alone should be enough—they are easier to set up and faster to run.

It makes sense to add unit tests after moving to a framework because Vanilla JS code is often difficult to test. Frameworks such as React, Vue, or Angular come with their own unit testing tools and best practices, so you should follow framework-related advice.

Good examples

In my work with mentees, I’ve had a chance to see this idea applied in practice.

Laundry

Gulfani Putra is working on an application that is for laundry services to inform customers about the progress of their order. It’s a practical and simple example: the idea came from inefficiencies that he had seen in local business and that could be addressed with a simple application. If you go to the project page at GitHub, you can see the power of a good README file. By reading it, you will get a pretty good overview of what, why, and how he is building.

Hexter

Wojciech Peczyk is building an application that randomly generates a color code: Hexter. The use case is straightforward to implement, and it allows showcasing all aspects of the project. In the case of features, it’s always possible to add more later on: things such as a button to copy the color to the clipboard, storing previously found colors, etc.

Summary

Writing a demo project is a great idea to showcase your ability to deliver useful applications. At the same time, it’s a lot of work: more than one expects before starting. That’s why it’s important to keep the feature set small, cover many aspects of the project in it, and make sure you can show it to others before you are completely done with it. If you manage to build a project that touches all aspects covered in this article, you will have a strong demo project to show anybody interested in your skills.

What is version control?

Marcin Wosinek — Thu, 11 Jan 2024 15:29:44 +0000

Version control is a basic but integral tool in software development. Many people don’t prioritize it while learning to program and, often, developers only start using it when they start their job. Let’s see what version control is and how it can help you even before you start working on professional projects.

Basics

When you program, you’ll have many interconnected files that have to be in a precise state for things to work. In the case of the simplest applications, you can manage files yourself. As the complexity of the application grows, however, the difficulty of tracking the changes grows even faster.

Version control is a tool to manage the state of the codebase. It’s an additional level of control on top of the files stored on the disc. So, along with your files, you have a code repository that stores additional information:

previous versions of code,
sets of changes that can be applied, or reverted, together, and
descriptions and metadata for sets of changes.

With version control, you can store code snapshots. You can think of it as a sort of ‘save’ for development—a place that you can always return to if you mess up something. Same as in games, saving your progress regularly helps to avoid being forced to do the same task twice.

Git

Currently, Git is the de facto standard for version control in the industry. You can safely assume that it’s all you need as a beginner—with a solid grasp of Git, you will be able to pick any tool that your employee could require you to learn.

Git is a distributed system—in a typical use case, everybody has a complete copy of the repository on their machines. The copies of the repository can be easily synchronized. Usually, you have a central, remote repository that is often called “origin,” and each developer synchronizes with this repository.

The centralized repositories are often hosted by external providers, such as:

GitHub,
GitLab,
CodeSummit from AWS,
or others.

Impact on productivity

Let’s see how using version control can improve your productivity.

Revert local changes

The first impact is in having a quick way to revert any changes you’ve made locally. Sometimes you need to change the code in many places to make one change. Without version control, getting back to what was already working could be difficult: imagine having to revert changes to five different files in your code editor. You can be as careful as you want, but occasionally, you will struggle to get back in time—unless you create snapshots of your working application with version control.

Integrate changes from many sources

When you have changes coming from many sources, it can be challenging to get them integrated. Even without changes to the same file, it can be difficult to find what was changed in what files when different developers build different features. Changes to the same file are almost impossible to integrate manually—you would have to check the files line-by-line.

Git tracks all changes separately, and it has a powerful feature of three-way merges: comparing two versions of the file that are being merged and the original state before they diverged. Thanks to this capability, Git can often integrate changes without developer intervention—and I have never seen those automated merges produce invalid code.

Restore past versions

Sometimes, you want to get your code to where it was in the past—Git has you covered. You have many options to achieve this reversion:

git checkout <version> at some version in the past—so you can see how the code worked at a given point
git reset --hard <version>—move your branch to the specific version, dropping changes that have been made since that point
git checkout <version> -- <file>—restore a given file to its state in some other version

When you’re working on a codebase, those features really come in handy.

History

The longer a project lives and the more changes that occur throughout its life, the more value can be found in its history. Well-maintained history, with well-described, atomic commits can provide insight into why things are the way that they are right now in the codebase. This information can help future developers make informed decisions about code changes. In another article, I wrote about creating a useful Git history.

Reverting some specific update

Git allows you to revert very specific sets of changes with git revert <version>. This command attempts to bring all affected files to the state before the change. It often requires manual conflict resolution, and it adds a new commit to revert the changes. This is another reason why you want your commits to be small, and contain closely related changes.

What goes into the repository?

Once we have a code repository, we can start using it. Let’s see what things are typically managed with version control.

Source code

The source code of our application is the most obvious example. In the case of a website, we will put all the related HTML, JS, CSS, etc. files into the repo.

Code that you maintain is the perfect case for version control. Take the following cases:

you need to store the precise state of the files—even an extra comma or a whitespace in one of the files could break the application
the files are text-based, so it’s easy to compare different versions
you manage all the changes—it’s possible to ensure that there is a logical connection between all changes bundled together

Description of dependencies

For the code that you use but don’t maintain, you’ll usually store only information about dependencies. In the case of JavaScript applications, those are package.json and package-lock.json files. The dependencies can be downloaded with a package manager in places where we want to run the code. Then it’s the package manager’s job to make sure the correct versions are installed.

Binary files

There are some binary files that you can expect to appear in your codebase. You can expect media files that are used across the application interface: logos or other images, files with sound effects, etc.

Git can manage binary files, but it's primarily focused on text files. When we store binary files, we cannot enjoy many Git features—such as help with conflict resolution or easy comparison between versions with git diff. Git repositories will store each version of a binary file in an uncompressed way. If you add big files, and will continue changing them often, your repository will grow quickly.

What stays out of the repository

Git is a powerful tool for managing files for your projects, but it’s not the right tool for all your needs. There are specific use cases that are better managed outside of a Git repository.

Database

Many systems require a database to function. In those cases, it could be tempting to keep a database alongside the code inside the repository, but it’s rarely a good idea for various reasons.

The life cycles of data and code changes are very different. With code, you create locally, test on a staging server, and finally deploy to production. With data, you want a different database for each environment, with some changes occasionally traveling across all of them in one direction or another.

Databases are likely to compress the data and store it as binary files—and as we discussed before, those are problematic in Git. The only thing you need for running the application locally is a demo database. You could get this with a special container filled up with the example data, or with a database initialization script that you store in the codebase. Both approaches are more suitable than keeping a database in the repository.

Built code

There is no reason to keep your build code in the repository. It’s a binary file, it will take a lot of space, and its value is limited. You can always rebuild it directly from code. For storing build results, you need some other solution as an artifact repository: package registry is one you can get from NPM for node modules and a container repository for things that are deployed with container images.

Dependencies

Adding your dependencies to repo (committing node_modules) has a few big downsides:

your repo grows considerably, with code that you mostly leave unchanged,
your commits will become less intelligible—for 100 lines of your own changes, you can get tens of thousands of lines in some 3rd-party libraries, and
some 3rd-party dependencies are installed differently depending on the operating system. It will become harder to share code between OSes with significant differences between them—for example, between Windows and macOS.

User uploads

In the case of websites, the user upload can end up inside the directory tree of your application. This is what I often saw when I was working on PHP websites. Nonetheless, those files don’t belong to your code repository—you need to find another way to manage them, and besides that, make sure you don’t remove them while deploying a new version of the application.

Repository in action

Let’s see some examples of a Git repository. You can explore the repositories with your local Git client or on hosting platforms such as GitHub. Let’s take a look at a lodash repository at GitHub.

Codebase

Git provides you a view of any version. The current state the repo:

or version 1.0.0 12 years ago:

Tree

One of my favorite views—all changes displayed on the commit tree. From main branch:

Commit diff

You can see the changes that were made in a specific commit as a diff to all the files in the project:

Attribution

If you want to know the author of the last change to a line, you can use the neatly named git blame command, or you can see the file in blame mode at GitHub:

Summary

Version control is a crucial tool in any developer’s toolbox. Not using it guarantees that, eventually, you will waste some time. Learning how to use Git takes effort, but it’s an investment that will pay off hugely when you program—even during your studies or work on personal projects.

Why IT projects are never done

Marcin Wosinek — Fri, 29 Sep 2023 05:47:07 +0000

Many projects I have worked on seemed simple at first glance. Nonetheless, there is always something to be done, and there is no end in sight. Usually, it’s not a problem—as long as there is money to finance the development. Let’s take a look at why IT projects are never done.

Complexity

Things are always more complicated than they seem at first. Often we have unexpected complexity in two places—the problem we want to solve and the solution itself. As we try to solve the problem, we learn about new aspects that make it more complicated than it looked at first. And the solution that we create often becomes more complicated than necessary. This leads to way slower progress, to the point when the requirements change at the similar rate as the code itself.

Technical surroundings

No project is an island. Any functional piece of code depends on countless things over which we have no control. If you look with perspective long enough—5, 10, or 20 years—anything can change: operating systems, programming languages, or ways the IT economy is running. From a business perspective, plenty of efforts take many years to become profitable.

I started my career in 2008, and over the 15 years since I’ve seen:

iOS (2007) and Android (2008) becoming important operating systems,
the appearance of Node.js (2009) and its rise to popularity,
Web platforms overtaking desktop applications,
the growing popularity of JavaScript, and
the disappearance of Flash and Java applets.

With changes of this scope, there is no way to create a future-proof project—at some point, you (or your successors) could be forced to rewrite everything on a new stack.

Third-party APIs

On a less dramatic scale, your application is likely to use some external providers: for managing payments, sending emails, or any other services. Given enough time, some of those providers will go out of business or rebuild their API and deprecate the version that you are using. Usually, there is some transition period, but it will likely be a few months rather than a few years. In a project with many competing priorities, this can feel like short notice.

Legal requirements

Similarly, the legal requirements can change from one year to another. In the EU, we had a big change with VAT and online sales in 2021. For many online companies, that meant plenty of changes in the code. They were forced to start dealing with VAT in every EU country that they were selling to.

The company where I work deals with brick and mortar businesses—we were not affected by online trade regulations. Nonetheless, we had an assumption in the code that there are only 3 levels of VAT—for example 0%, 7%, and 21%. This worked fine for us for a long time. It turned out to be a problem, however, when one of our customers expanded to a new country. Over there, not only were the percentages different, but there were also simply more levels. When you have to change a fundamental assumption like this, you are likely to get an avalanche of changes in your codebase.

Code dependencies

A mature JavaScript project has many essential dependencies:

the framework it uses
unit test library
end-to-end solution

Creators of those tools try to smoothen the upgrade path as much as possible, but they have a trade-off between the ease of upgrade for you and how much they can change. And when the tool is discontinued, moving to a replacement is guaranteed to be a lot of work.

When I started working with AngularJS, Protractor was an impressive end-to-end tool—the best tool available for doing integration testing of angular applications, and probably for any frontend application. Now, 8–9 years later, it’s been a few years since it got an update, and in August 2023, it reached its end-of-life. There are better tools available now, but moving four hundred tests I have on Protractor would be a huge project.

Product discovery

Product discovery is a nice term that covers the fact that it takes time to find the right combination, where:

your customers have a problem,
you can address this problem at scale with an application,
they are willing to pay for using your solution, and
what they pay covers your costs.

You can expect this process to take time and many iterations. Some of the iterations will require implementing a feature and then seeing if it's useful to customers, and whether it makes money for the company. As long as the product is used, there will be some ideas worth checking.

How to manage it

So we know that the IT projects are unlikely to be done—that there will always be some changes that require updates to the code. What can we do about it?

Plan long term

There are always dead-lines to be met, but make sure that quarterly goals will not ruin the long-term future. Think about it as a marathon, not a sprint. One thing worth investing time in is code quality. Some compromise and flexibility will be needed, but think about overall architecture, consistency, and best practices of the stack you use. Rushing too much can lead to making a code so difficult to maintain that it will become impossible to make the simplest changes.

Document what you are writing. For a start, maintain a README file with instructions on how to start the project. Write documentation for classes and methods, preferably in a way that makes it easy to extract the documentation—for example, JSDoc.

Write automated tests. Unit tests slow down development when you are learning to test at the same time as you write code. Once you are proficient with testing, developing tests along with your code can be faster than the code alone. When you write code and tests together, you have a quick way to recheck all the edge cases you want to cover.

Keep the team around

Even with the best effort at documentation, there is a lot of knowledge that is stored only in the minds of your team members. What decisions were made 4 years ago and why; how similar bugs were fixed the last time; what code is responsible for what. Every time a team loses someone, part of this knowledge is irreversibly lost. It’s a shame the industry got to the point where changing jobs often is the best advice for developers. If you can influence that, it would make sense to make sure the devs are happy with the job and the conditions and stay as long as possible.

Why is it difficult to get onboarded on an existing project?

Marcin Wosinek — Wed, 20 Sep 2023 04:34:09 +0000

Often, when you start working on a project, you will find yourself struggling with the most basic task: getting it up and running on your machine. This can be a frustrating process, so let’s see what causes those problems and how you can handle it.

Developer experience

User experience (UX) focuses on how the user interacts with the system and makes their journey as smooth as possible. Similarly, we could consider developer experience with the system. Usually, in small projects, the priority of improvements that benefit developers is low enough to never be done.

The examples of good developer experience come from large projects and products targeting developers specifically—for example:

Cypress for end-to-end testing,
popular frameworks, such as Angular or React, or
GitHub, CircleCI, etc.

Small companies, or one-person open-source projects, often lack the resources needed to make your journey pleasant. Simply, if you have to onboard a new developer once a year, it can be cheaper to have them struggle for a bit then to make the installation smooth.

Ever-growing complexity

Projects tend to grow in complexity with time. All the time, things are being added:

new features
refactorings that take forever to be applied on the whole codebase
dependencies that become outdated

If you have a project that lasts for a few years, it will definitely be more complicated than something that would be written now.

The accumulated complexity often spills into troubles with starting up the project: you might find a mismatch of technologies, and they can interact in an unexpected way when you start the project on a new machine.

Documentation challenge

Explaining things in writing can be difficult, but this doesn’t often receive enough attention. Even if the team you join tries to keep docs of a decent quality, there is always one challenge left: they have to assume some level of knowledge in the reader. There is always a trade-off involved with that—when you explain too much, it will be more work to write and maintain the docs. Moreover, you could flood the reader with too much text. If you explain too little, the documentation will lack crucial information for some people.

Some common examples of things you could struggle with:

Plenty of programming (C++, Node.js, Python, Git) and internet tools (Apache, Nginx) come from Unix-based systems—if your background is in Windows, then you will be struggling with some underlying concepts.
Many programming tools are built with the command line interface (CLI) in mind: the most important is Git, but other tools are often important as well—ESLint, Prettier, etc. If you have never used CLI tools, you might have gaps in knowledge that no project documentation will try to address.

When I was starting to learn programming, I often got stuck on one or two sentences of the book that described a step I couldn’t overcome. Luckily, as time goes on and you gain experience, cases like this become less common.

Unexpected differences

There can be many differences between your machine and whoever builds the system you’re trying to start now.

Differences in operating systems tend to cause the biggest issues. Linux's distros and macOS are usually compatible enough to be considered one camp. On the other side, we have different versions of Windows. If you join a project that was built on an operating system very different from yours, then you are likely to discover some incompatibles that nobody expected. In JS projects, it’s often expected to be able to run it on whatever OS you like, but it can require some effort to make it truly compatible between systems.

Another surprise can come with the ways of installing tools you need to run the project. For example, last time I checked, Windows had three ways of installing Git—each method doing things slightly differently. Similarly, Node.js or Python can be installed in many ways on Unix systems, and sometimes developers forget about the ways that are different from their preferred one. I always use nvm to manage my Node.js, but it’s not what you find when you go to Node.js website to check for installation guides.

Containers to the rescue?

Containerization, which was made popular with Docker, makes it simpler to move across machines and OSes. Unfortunately, you would still be lucky to have your whole developer journey paved with well-prepared, ready to use images. At my job, I had a good experience using Docker as a shortcut to getting a backend up and running quickly locally. Nonetheless, I still struggle to move the whole developer experience to containers so that everybody has the same dependencies available. Containers are a great tool, but any work at optimizing developer experience faces the same lower priority that we mentioned earlier.

How to deal with it

Accept that it will take time. If your team tells you that the setup can be tricky, or that you can expect some issues—trust them, and don’t get frustrated.

Ask questions. I’ve seen more devs erring on the side of asking too few questions or too late rather than asking too many or too early. If you don’t want to be annoying, or just want to be somehow independent, set an alarm clock to add an hour or two and ask a question when it rings if you are still stuck. Then you can take your time to describe your issue well, following the tips I shared previously.

Improve the doc. Ultimately, try improving the experience for the next person that will take the same path. The places where you struggled are valuable indicators of where the docs are lacking. Maybe “install Node.js” needs more elaboration with respect to “from where” and “how.” Perhaps you are the first one to run the project on Windows, so you could help others take the same path quicker. In a way, during your installation, you become a beta tester of the documentation, and with everything running, you have enough experience to improve the docs.

What was your experience with getting onboarded on a project?

Please share in the comments—I’m truly interested in hearing how it goes for newcomers to projects.

How to write maintainable code: Straightforward logic

Marcin Wosinek — Thu, 07 Sep 2023 11:49:53 +0000

Maintaining code is more complicated than writing it. Before you make any changes, you need to understand what is there already, how it was supposed to work, and how it works now. The difficulty of this task will depend on how the code was structured and if it’s an easy read. In this article, I’ll show you how you can make your code more readable and therefore easier to maintain.

Obvious entry points

When you start a ticket on an application, usually you have some information about where the change or fix should happen. You can make linking that place to the code easier if you consistently use some convention for naming and placing the files. Let’s take a look at a few examples.

Component-based app

In my day job, I build and maintain a few Angular applications that are built with components. Each application has many routes defined, and for each route there is a top-level component that is responsible for this view. The naming convention we use is as follows:

simple route: /home-page—<home-page>
nested route: /long/nested-route—<long-nested-route>
route with parameter: /user/:id/edit—<user-edit>

In this way, if I get the route where the changes should happen, I can immediately find related component files.

Backend

On the backend, we have a few constraints put on the routes we use. The API is loosely inspired by the REST approach, and each endpoint is related to one of the collections that we have in the database. The routes are in a format /collection/operation—for example:

/users/get
/transactions/get-report

The code that is called by those endpoints is organized in files by the collection: so in one file we have methods related to users' collection and in another we have methods related to transactions. In this way, based on the first part of the API route, I know where to look for the code.

Avoid unnecessary jumps

One of the ways that I often see makes the code complicated is by sending the reader through many unnecessary jumps. When you read code, it’s inevitable that you will need to do some jumps between different parts. This becomes a problem when the jumps are many and unnecessary. Some examples based on what I’ve seen in real-world code:

a function that does nothing besides creating an alias for another function

function A(param1, param2) {
  return B(param1, param2)
}

this can make sense for some refactoring, but it would be good to have it in a temporary situation,

named callback functions defined away from where they are used:

function success() { /*..success..*/}

function error() { /*..error..*/}

getPromise().then(success, error)

The same thing would be simpler to read if it were:

getPromise().then(() => { /*..success..*/}, () => { /*..error..*/})

expectations in a test set in variables, away from where they are used:

const expectedObject = { /*..some big object..*/ };

/*..many lines of code..*/

expect(result).toEqual(expectedObject);

Whenever we have a jump in code, we make it slightly more complicated to read. Let’s make sure that this inconvenience is balanced by some benefit—that there is a good reason to do it this way.

Keep it simple

The flow of your code should be straight. It should be easy to draw a chart of how the logic flows through the application and how things depend on each other. There should be no circular paths in your code, unless you are doing some recursion on purpose.

It should be your goal to be always able to explain how user actions or some external events lead to data changes. If you cannot easily tell what is responsible for what, then it’s very likely your code is chaotic and difficult to follow.

Displaying data

Of the simple cases is transforming the data for display. It could be one of many things:

formatting dates in a user's locale,
translating into user’s language,
combining many properties of an object into one, ready to display string, or
filtering an array based on a search.

Each of these operations should have an easily identifiable input and output format and should be written in a form such that a reader knows what goes in and goes out.

Formatting data for display should leave the original untouched—there is no reason to change the data just because it is displayed in some place.

Changing state

When you change the state of your data, it should be possible to easily identify the following parts of the code:

source of the change—button that was clicked, the event that occurred in the system, etc.
the change itself—the code that checks the constraints and updates the state of the data
saving the changes to the storage—this could be an update to the database in the case of backend code or calling a save API in the case of the frontend

If, for some reason, it’s not easy for you to identify what parts of your code are responsible for some of those points, then reading this code will probably be pretty confusing.

Testability

All the things we discussed here are consistent with writing testable code. Small, well-defined units with clear responsibilities are easy for developers to understand—and easy to test. For me, writing tests is a good exercise that can teach you to write more readable code: just pay attention when testing starts becoming painful and when the code becomes too convoluted to easily work with.

Learn more

If you are interested in hearing from me when I publish some new material about programming or related topics, you can sign up for my mailing list.

Writing maintainable code: Data model

Marcin Wosinek — Fri, 01 Sep 2023 07:45:01 +0000

In programming, a lot of the challenge is related to organizing data in a structure that makes sense and which helps to solve the problems and facilitates understanding of the code. In this article, I’ll show you what tools you have at your disposal and how to use them.

Building blocks

To simplify our discussion, let’s focus on what we have available in JSON—the data format that was created based on how data can be hard-coded in JavaScript. In this way, we don’t need to think about the performance implications of different data structures—we only focus on the usefulness of the data model.

Primitive values

These are the most basic value types we can have in our program. In JSON, those values are:

boolean—a true or false value,
a number—a floating-point value,
string—a sequence of letters, and
null—a missing value, which is still useful for expressing certain states.

Already with those basic types, we have the possibility of addressing the same thing in different ways. For example, for customer type, you could use some of the following:

const customerType = “retail”;—which could accept any other string value, both valid or invalid ones
const isRetail = true;—a more rigid approach: its two options are obvious and clear, but it has no way of allowing more possibilities
const customerType = 2—can be expanded, but requires documentation for understanding what each number means

Anything you decide will impact how easy it will be to change code later on. As you are picking the value type for your variable, it’s good practice to try to think about possible changes and pick a type that fits well for both current and future needs.

Arrays

Arrays are ordered lists of values. The JavaScript arrays can mix any types of values, for example:

const someArray = [ 1, 2, “test”, [“another”, “array]];

Although it is a valid array, mixed types arrays are confusing to work with. It’s way easier to stick to keeping the same types of values in an array.

An important feature of arrays is that they are ordered. This makes them a great match for places where you care about similar data points and where the order is meaningful. For example:

products in cart—you definitely want to display items from a cart in the same order; and
students in a class—each one of them has their list number.

Arrays work well when you access many values in sequence. It’s less useful when you want to find whether a given value is in an array. When I find myself often using includes() to see if an array has some object I’m looking for, I take it as a potential sign that I should reorganize the data structure.

Objects

The object is a structure that consists of a set of key–value pairs. The structure is unordered, so it makes it a suitable choice for many places that don’t fit the array. Each value on an object can be understood independently of all the rest, so you can mix different types of values without worry. Example of an object:

const user = {
  login: “lorem.ipsum”,
  email: “sin@dolor.com”,
  age: 24,
}

Objects are a good match for collections of named, unordered properties. For example, a set of permissions:

const hasAccessTo = {
  blog: true,
  blogAdmin: true,
  userAdmin: false
}

Built-in objects

JavaScript provides many object types that you can use on the code side to keep your values in a more suitable form—and with methods that make them more usable. For example:

Date—for date time values,
Set—for unordered collections of unnamed values that don’t repeat, and
Symbol—a non-string identifier that will not collide with other values.

Those types are very useful, but in communication that goes through a web API that uses JSON to represent data, they all will be serialized to value types described above. In my daily job, where I program business applications, the only types that I use regularly are dates.

Pick the appropriate structure

The way we organize data impacts what can be easily done in our code. Let’s take a look at the permission example from above:

const hasAccessTo = {
  blog: true,
  …
}

This value can be used easily in conditional cases such as: if (hasAccessTo.blog).

The same requirement for a permission list could be met with another data structure:

const permissions: [{
    resource: “blog”,
    access: true,
  },{
    resource: “blogAdmin”,
    access: true,
  },{
    resource: “userAdmin”,
    access: false,
  },
]

The same condition from above would need to be replaced by:

const blogPermission = permissions.find(x => x.resource === ”blog”);

if (blogPermissions?.value) {
…

This is much harder to read, and it’s easier to write code that will throw errors in some specific cases. By using arrays, the only thing we “gain” is the order of permissions, which shouldn’t matter.

Create a draft

There are plenty of things to consider as we organize data in our codebase, and calls can get complicated pretty quickly. To avoid rewriting code, it makes sense to create some form of draft for the structures. In my case, I often describe them with the names I plan to use in the tickets I’m going to work on. Often, when you see your structure design written down, you’ll notice some issues with it.

Keep on improving

The data structure for your code will never be finished—it should keep evolving with your application. Changing names after they appear in many places in code, and in databases, will be painful. However, it is necessary because otherwise the mismatch between names and their current understanding will only grow as things change over time. This is a common source of code debt that often slowly piles up until it makes working with the code an unpleasant and unproductive experience.

Learn more

If you want to receive an occasional email from me about programming or related topics, you can sign up here.

How to write maintainable code: Naming things

Marcin Wosinek — Wed, 23 Aug 2023 04:23:06 +0000

Using the right names is an essential part of writing maintainable code. For a computer, any name will work just fine—they either match or not. For the humans who read the code, the names are the first thing they have in mind as they work on the code. We all have some capacity to deal with a wrong name. If necessary, we can do a mental translation when the name doesn’t match the concept, or we can ignore some typo. But doing so uses both our memory and mental capacities. It’s easier and more efficient to work with the code that has the naming done right.

One name for one thing

For organizing our stuff, the general advice is to have a place for everything and everything in its place. Similarly, our lives will be much easier if all the people involved in the same project use the same terminology. Usually, we developers don’t have a perfect understanding of the domain in which the project is used. As a result, it makes the most sense to learn the terminology that is used by our business colleagues and use it in the code as well.

Parts of speech

To create terminology that is easy to use, it makes sense to apply some of the grammatical knowledge we all got from school. Different types of words fit better in different use cases:

nouns are a perfect fit for objects or primitive values: user, accountNumber, customerEmail
adjectives work great for some Boolean flags: allowed, disabled
verbs match functions or object methods user.login(), shutDown()

You’ll likely find cases where it would make sense to bend this rule, but for me, it makes sense to try tweaking the names to match this pattern. For example, for a method that checks the current state, I would use user.isActive() instead of user.active().

Avoid abbreviation

I’m always skeptical of abbreviations as names in code. Many abbreviations are obvious only when you are deep in the context of the code. A reader who is new to the code and the domain can be confused. Making names short doesn’t improve meaningful metrics. When we write code, we usually use code suggestions, and most lines fit on the screen anyway.

When there is potential conflict between brevity and clarity, I always prefer to stay on the side of clarity. The only abbreviation I can think of now that I’m OK with seeing in code is VAT. It’s so commonly used that it is easier to understand than its expanded form: value added tax.

Pronunciation

All names we put to code are used in two ways. In writing—in code or documentation, and in speech—and when we talk about them. It’s important to think about both use cases when choosing the name. Pronunciation is often another reason to avoid abbreviations: they often miss vowels, and you may need to say it letter by letter.

Avoid name collisions

Try not to reuse the names with different meanings in other contexts. If you use some synonyms instead, then it will be easier for developers to intuitively understand the terms correctly when they hear it—without overthinking about the context in which they were used.

Brainstorm ideas

I have a high bar for naming things. Some names are easy to create; others are more difficult to come up with. For the most complicated cases, I try to write down as many ideas as I have in the ticket that will introduce a given concept to the code. I try to generate about 3 to 5 ideas—if it’s very difficult, I write down even the ones I don't like. With this in place, I ask my colleagues for their opinion. In this way, I get an external input and spend more time on thinking about the name. It helps in making the decision.

If you want to get occasional emails about programming or related topics, you can sign up for my newsletter here.

How to manually test a web API

Marcin Wosinek — Wed, 16 Aug 2023 05:51:47 +0000

A few weeks ago, I showed the basic ideas and terminology of web APIs. In this article, I will demonstrate how to apply this knowledge, and try an API with some manual testing.

Tweak query

The easy way to start testing any API is to find an example that works—and then tweak it. You can pick any website and see what requests it does. For example, when you open developer tools in Chrome and reload my blog at how-to.dev, you can see plenty of requests sent by the website:

In the list, we have a few types or requests:

script or stylesheet with names 4421.a65a… or 6238.6ee7…,
fetch with names such as user, tags, events,
xhr with name event,
and some other types with resources: svg, avif, font.

We are the most interested in fetch and xhr request types. Both could be triggered from the JavaScript side and used for talking to the web API. The other requests we can see here are requests to load some static files—the code or some media content. For each of the queries we see on the list, we can copy one of the formats:

Copying the code allows you to easily do one of two things:

rerun the query exactly as it was done by the application, or
tweak the query to see how the API works with different input.

Fetch

Fetch is a JavaScript interface to communicate with servers—for example, to talk to a web API. You can read more at MDN. Here we will see our example query:

fetch("https://how-to.dev/api/user", {
  "headers": {
    "accept": "application/json",
    "accept-language": "en-GB,en-US;q=0.9,en;q=0.8",
    "baggage": "sentry-environment=vercel-production,sentry-release=736267205a61e0548a85c08aab089d3f1421126b,sentry-transaction=%2F%5B...slug%5D,sentry-public_key=0fbf92e944b8468cb9706e15c488c84e,sentry-trace_id=a2a1dbab6f5b4c619173000812050469,sentry-sample_rate=0",
    "content-type": "application/json",
    "if-none-match": "\"as45c9ut8od\"",
    "sec-ch-ua": "\"Not/A)Brand\";v=\"99\", \"Google Chrome\";v=\"115\", \"Chromium\";v=\"115\"",
    "sec-ch-ua-mobile": "?0",
    "sec-ch-ua-platform": "\"macOS\"",
    "sec-fetch-dest": "empty",
    "sec-fetch-mode": "cors",
    "sec-fetch-site": "same-origin",
    "sentry-trace": "a2a1dbab6f5b4c619173000812050469-8d225d0201152147-0"
  },
  "referrer": "https://how-to.dev/what-is-an-api",
  "referrerPolicy": "origin-when-cross-origin",
  "body": null,
  "method": "GET",
  "mode": "cors",
  "credentials": "include"
});

As you can see, there are a lot of details. To run the query, paste this code in the console in dev tools and add .then(console.log) at the end of it. The fetch function returns a promise, and adding console.log as a callback will show us the output right there on the screen.

You can modify any of the parameters provided to the call, and in this way you can see how the API will behave.

The big advantage of this approach is that you will reuse the credential information already available in your browser. If you have an open session, there will be a cookie in your browser, and it will be sent with your request: in this way, the server will know you are you, and where you should be given access.

GET request

Another option to test the API is to put the URL where you want to send your GET request into the address bar. By default, the browser does the GET request to the endpoint and displays the response on the screen. It will not always work as expected: in some rare cases, the API can be flexible enough to support different formats depending on the query headers. In such a case, it may be that address bar requests show HTML, whereas the API call gets JSON.

Demo API

Httpbin is an example API we can use for our testing. Its main page is some documentation that shows all the endpoints available for us:

Let’s try visiting some of the endpoints directly from the browser.

Address bar

When you open one of the endpoints http://httpbin.org/uuid you will get a response similar to this:

You can see more details by opening the dev tools and the network tab. When you refresh the page, you can see all the headers that were sent and received by the browser:

You can use this approach to test GET requests to web APIs.

POST request

Creating a POST from scratch is more complicated. You could try writing fetch calls, but as you saw earlier in this article, they can be quite complicated. Let’s use an API testing tool instead.

Hoppscotch

Hoppscotch is an API development tool that we can use to send any type of request—POST included. If you’ve heard about Postman, this is an open-source alternative. For the testing, I’ll send a POST request with some JSON data to Httpbin’s POST endpoint. At the initial screen, I set the URL to http://httpbin.org/post, the method to POST. In the Body tab, I set the Content Type to application/json and the Raw Request Body to:

{"test": 123}

Here’s the request just before sending:

The initial attempt fails because we are accessing an external server. There are few options to address it, with Proxy being the easiest to get you off the ground:

The result after retrying the request:

As you can see, the Httpbin API just returns a bunch of technical information about the request and the body.

This simple test skips the issue of authorization—many POST requests are only available to the user that is logged in on the server and fail for anonymous users. Covering this concept fully is a topic for another article.

Want to learn more?

If you are interested in learning more about API or related topics, you can sign up for occasional emails from my newsletter.

How to build an impressive demo project

Marcin Wosinek — Wed, 09 Aug 2023 05:23:50 +0000

When applying for a job, it’s good to have a demo project to present as an example of your work. In this article, I’ll show you what to focus on while building such a project. I share conclusions from being on both sides: applying for a job and reviewing projects of applicants.

Demo project goals

A demo project is a good opportunity to show off the wide range of your skills. You can do this the best by expanding your project in depth—having a simple set of features for the application but implemented with high-quality code. With a simple feature set, you can focus on showing all the aspects of programming that you would like to work with. With a demo project, you have an empty canvas you can fill in as you please. The only constraints are your creativity, skills, and how much time you want to put into it. You can use it to show the breadth of your knowledge.

While working on a demo project, you don’t have to follow guidelines imposed on you by other developers. You can use this opportunity to show exactly what you mean by good, quality code. Quality is something that good workplaces pay a lot of attention to. Even in places where they say we have no time for quality code, it’s very likely that the technical interviewer will prefer people who can deliver maintainable code.

By delivering a demo project, you prove that you can ship something. Any project that is completed is perfect proof that you both have the skills necessary to create it, and that you are not a perfectionist who can’t finish stuff. Both things will be valued in a workplace.

Side goals

It can be tempting to add some side goals to the project to make the time investment more worthwhile. Depending on your situation, this could indeed be a good idea, but keep in mind that by adding additional priorities, you either water down the original purpose of the project, or you increase the scope of your undertaking. If you are thinking of applying for a job soon, try starting simple with technologies you know and add the new ones later on—if you have time.

Project scope

Building a project from scratch is always a lot of work. Typically, projects go over the initial budget estimation: just look at any construction project in your area. If you follow my advice of demonstrating many of your skills, you will already have a lot of work to do. To avoid starting a project that is bigger than you can finish, the best idea is to keep the feature scope as little as necessary. You can always expand the feature scope in the following iterations—exactly the way you do in agile. If you want some inspiration for simple demo projects, here you have a few examples of what I discussed on this blog:

a simple application to store a sequence of data points on energy consumption
a hello world app

Frontend

As a frontend developer, I’m always focusing the most on that part. Even if your priorities are elsewhere, the frontend will be the part of the application the reviewer interacts with, so it makes sense to invest some effort in it.

Depending on your priorities, you can include different qualities to it:

If your dream job involves UI/UX design, you can put in the effort to make it pretty. Otherwise, a standard UI framework or even no styled elements will be OK.
If you aim for a frontend job with some framework, you can use this framework in your project. Otherwise, vanilla JS could be an interesting showcase for how you solve some common problems on your own.

Backend

For many applications, you will need some form of backend. Depending on your career goals, you can try some “serverless” backend from the cloud, or build a server for your application yourself. If you aim for full-stack or backend positions, this will be a great exercise. It will complicate a lot of your local and deployment environments, but it will bring your demo application to be much closer to real-world cases.

With backend and frontend work, you will be confronted with many aspects of development that are not present in a project that involves only the frontend. For example:

mono-repo vs. poly-repo, a topic I discussed in another article
true end-to-end tests where you check both parts of the app

Covering those aspects in the demo app will be a great way of showing your capacities to the interviewees.

Database

Adding a database to your project would be yet another level of complexity. If you aim for a backend or full-stack job, it would be a great opportunity for you to show your work across all the parts of the stack. When your focus is the frontend, it will probably make more sense to skip the database and just keep data in the server’s memory.

Technology stack

You will need many technologies to get your project up and running. Make sure to choose things that make sense together: use a combination of technologies that are often used together and avoid adding libraries that overlap with the features they provide.

If possible, try using tools you are familiar with. Learning new things will make you slower in creating the application, and it’s more probable that you will make some mistakes while using it.

What to include

When I review projects for other people, I focus on whether and how they approach certain aspects, which I discuss below. This list is my personal list, and others will put different weights on those things, but I’ve noticed many senior developers are paying attention to the considerations I mention here. At the same time, some of those things are things ignored by junior developers.

README

When I visit a project for the first time, I expect a README file that will quickly bring me up to speed with the project. A great example is at date-fns:

You can find more about how to write a good README in an article on my blog.

Deployed application

When you try to show what you can build, it makes sense to make it easy for people to see the application in action and play with it. This gives them a context that is helpful to understand the code and will demonstrate the scope of the project. Besides, deploying is a critical part of the project life-cycle, and it makes sense to show you can take care of that too.

If you build only the frontend, the deployment will be effortless: you can use GitHub or GitLab pages, or Netlify. Adding a custom backend or database will require more effort—the easiest would be to find an affordable cloud provider and deploy to the cheapest instances there. I liked the simplicity of the offer from Digital Ocean, but the details of the offering of those companies change every few months.

CI/CD

Continuous integration (CI) is a piece of your project’s infrastructure that checks whether everything is working as expected after each commit. Continuous delivery (CD) deploys the last version somewhere that it can be tested: in the case of a demo project, it could be to the main environment because you don’t need to create a production and staging split.

For implementing continuous integration and delivery, you can use an offering of your Git hosting provider: for example, GitHub Actions or GitLab CI/CI. Another option is a dedicated CI service, for example, CircleCI. All those solutions have similar capabilities, and for simple pipelines, it shouldn’t matter much which one you are using.

Setting up CI can be more time-consuming than expected. As you tweak the configuration, you often need to wait for many minutes to see the impact of your changes. Running the code on external machines makes troubleshooting more complicated.

Linter

Linter is a program that analyzes your code, looking for errors or potentially problematic patterns. Each programming language has some tools like this available. In my frontend work, I use:

ESLint for JavaScript and TypeScript code,
Stylelint for CSS and SCSS, and
HTMLHint for HTML.

Those tools help to catch little, annoying bugs and teach you what structures in code you should avoid. They often have extensive configuration options, and can be expanded by plugins. I see no reason not to use them in any project, let alone a project where you have to show off your skills and dedication to the craft.

Code style

As a developer, you spend more time reading code than writing it. Making the reading experience pleasant is important, and many senior developers insist on keeping the code as consistent as possible. Luckily, we have tools that take care of applying the code style across the project. For the frontend, Prettier is a tool that covers all JS/TS, HTML, and CSS. You can read more about it here.

Unit tests

The goal of unit tests is to check whether the part of the application—methods, classes, etc. are doing the thing they are supposed to do. There are many tools in JavaScript that you could use for writing unit tests, for example:

Jasmine
Jest
Mocha

You have probably heard about the importance of unit tests many times before. On my blog, I have 2 related articles: how to write unit tests for a practical guide, and what are the benefits of unit tests.

End-to-end test

End-to-end (e2e) tests check that the application works as expected all the way from the frontend through the backend and to the database. Those tests can be complicated to set up because there are plenty of moving parts—frontend, backend, database—and they all should work fine both locally and in the CI setup. Even though it could be difficult to get it right, those tests allow automating a lot of repetitive quality assurance (QA) work. Including them in your demo project can be a great way of showing you care about the quality and efficiency of the development team.

There are many e2e frameworks available: for example, Cypress, Playwright, and Nightwatch. Unless you have a specific reason to prefer some of them, for the demo project, I would use Cypress—it’s the most popular option. Even if the team uses other tools than Cypress, they will definitely recognize it.

If you are new to automated QA, you might wonder what’s the point of having unit and e2e tests in one project. Many teams create both types of tests, and I went through reasons why it makes sense in another article.

Codebase documentation

I already mentioned the README file that covers the main purpose of the project, and how to start playing with it. Besides this top-level documentation, it’s very helpful to explain briefly the purpose of the classes and methods you write. The best place to do it is in the code—so you can read and update the description as you work on the files. At the same time, it’s good to have the documentation available in other places too: as suggestions in your code editor or on a website other developers could access without downloading the code.

JSDoc is a popular syntax for adding in-code documentation to JS projects. It integrates with many different tools—good code editors will manage to parse it and use it for code suggesting, or it could be built static.

Meaningful commits

One of the things I pay attention to in projects is the quality of the commit history. A good project history has the changes organized in commits that make sense as a whole and are described in a meaningful way. Well-maintained code history makes it much easier to understand the changes when one reviews code and simpler to look for a reason why something was changed. Small commits, with related changes, are easier to revert if necessary. I wrote more about how to use Git repositories efficiently in a previous blog.

Want to learn more?

If you are interested in learning more about building projects or other development related things, you can sign up for an occasional email from me here.