DEV Community: Spyros Argalias

Defensive & offensive programming

Spyros Argalias — Sun, 16 Jan 2022 13:09:42 +0000

Defensive programming is a term that many programmers have heard of. It's related to error handling and having correct programs. For some programs, defensive programming is essential. For others, it may be useful to use here and there. Along with that, there's also offensive programming.

In this article, we'll start by examining "normal programming". We'll examine it first because some people mistake it for defensive programming. However, this is something that you should do regardless of whether you do defensive programming or not.

Then, we'll examine defensive programming, followed by offensive programming.

Normal programming

Normal programming means to have all the checks that are necessary in your code. It also means to always handle certain types of errors.

Necessary checks in code

Some code needs a lot of conditionals. It can feel like you're being "overly defensive" with the number of conditionals you have.

One example of this is checking for null (the billion-dollar mistake). Nulls and null checks are very tricky. Many codebases need if statements for them all over the place.

Another example is validating user input. You need to have many checks to ensure that user input is valid. Your program needs to handle it very harshly. Otherwise, you'll have security vulnerabilities.

But that's not defensive programming.

Rather, something like forgetting a single null check is a bug. They're not unnecessary checks that you do "just in case". They're necessary checks. The value will be null sometimes and that's normal. If you forget a single one, you have a bug. No questions asked.

Necessary error handling

Error handling is very important in programs. You always need to consider how your program should respond to errors.

This also depends on the kind of error.

Generally, most programs handle "expected errors" which are out of their control. For example:

failing to send a network request because the network connection dropped.
failing to find a file because a user deleted it.

It would be very bad for the user experience for a program to crash on these errors. Also, it's relatively easy to handle them.

As a result, most programs handle these, even if they're not doing defensive programming. So, again, this is considered "normal programming", not defensive programming.

A different kind of error is a bug. In most programs, these errors are considered "unrecoverable". The rule-of-thumb for most programs is to crash on these errors and to not handle them.

Defensive programming

In my interpretation, defensive programming is about fault tolerance. It means going above and beyond to ensure that your program continues working. It's used for certain programs where you need maximum:

availability
safety
security

Example use case of defensive programming

One example of defensive programming, as Adrian Georgescu writes on his post on NASA coding standards, is for code used in space exploration missions.

That code is developed once and sent to space. If it goes wrong, that's billions of dollars worth of work lost.

For that kind of code, you need to take extreme measures. The code must work correctly, without crashing, no matter what.

This is very different to your average program. With your average program, bugs aren't generally a big problem. Your program may still be usable even if it's buggy. In the worst case, a problem can be fixed manually by calling customer service. If the program becomes unusable, you can crash it and restart it. If it's a back end program, there are probably multiple servers running it. If it's a client, the user can restart the program themselves. In a really bad case, you can update the server code. You can even go to a physical server manually and restart it.

But, with certain critical software, you can't do that. The software has to always work properly.

The problem is that people aren't perfect. We create bugs. Not to mention that other errors may occur that are outside of the program's control (such as operating system errors). This means that the program may fail.

But, that's not an option with some software.

As a result, you need to do everything in your power to prevent failure.

How to do defensive programming

Defensive programming primarily means doing everything possible to ensure your program is working correctly and will continue to work correctly. This can include:

having very good software development practices.
having many checks in code to double and triple check that everything is working at all times.
optionally, having error recovery mechanisms. That way, if something goes wrong, maybe the program can recover.

Good software development practices

The first step is to make the code as bug-free and as easy to work with as possible.

That means that you need things such as:

very strict QA
very thorough tests
very thorough runtime monitoring
very strict coding and development standards. In fact, you may ban certain patterns or language features altogether, such as recursion.
good general software quality
source code that's easy to understand
software that behaves in a predictable manner

Those points are important for all software. However, they're critical for defensive programming. After all, if your source code isn't well tested or easy to understand, it could have bugs. This defeats the point of defensive programming.

Extra checks

Code with defensive programming tends to have many extra checks. The checks are there to catch bugs. They wouldn't be needed if the code was completely bug-free. Checks that aren't intended to catch bugs fall under "normal programming", not "defensive programming".

You have conditionals in the code that check whether something, such as some state in the program, is valid. If a check fails, it shows a bug.

At that point:

if the program is in development, you can crash it and fix the bug. This is the same principle as using assertions, during development, in offensive programming.
if the program is in production, you can run error recovery (if you've implemented it) so the program can continue working.

The common case is to crash the program and fix the bug. During development, you hope that the combination of tests and extra checks will catch all of the bugs. Then, when the program is in production, it should work as intended.

Another benefit for these checks is that they catch errors early. The more checks you have that the intermediate state is correct, the sooner you'll catch bugs. That makes debugging easier. It also means that you can start error recovery earlier.

Finally, you may be able to implement some error recovery. Then, if a check fails, you can run your error recovery code.

You can have as many or as few checks as you need. You'll have to decide what to check based on risk analysis. Some important checks are probably results involving important calculations and data. Some less important checks are things like checking function arguments or constantly checking state after simple operations.

Here are some examples of checks you might have:

Example with checking function arguments

You can check whether a function is called with valid arguments. The arguments should have the correct type and range.

Here's a code example:

function foo(nonEmptyString, naturalInteger) {
  if (
    typeof nonEmptyString !== 'string' || // if it's not a string
    nonEmptyString === '' || // if it's the empty string
    !Number.isInteger(naturalInteger) || // if it's not an integer
    naturalInteger < 1 // if it's not a natural integer (1 or more)
  ) {
    // crash the program
    // or handle the error here
    // or throw an exception so some code higher up handles the error
    // or do anything else your error recovery implementation requires
  }
  // code for normal function execution
}

Example with checking the results of data calculations

Another example is checking results involving data.

Normally, you would only check some data when you first receive it. For example, if a user submits some data, you would check it to make sure it's valid.

Then, you would work with that data. You might format it or transform it in some way. You would have tests to make sure that these processes work correctly.

In theory, you shouldn't need to also check the final result. The initial data is valid. The code you process it with works correctly. Therefore, the end result should be correct.

But, if you're doing defensive programming, you might have checks on the final result too.

Recovering from unexpected errors

The steps mentioned so far try to reduce the number of bugs in your program. However, there might still be bugs. For that reason, you might want to implement error recovery.

This might require a lot of thinking. It might even need to be part of your feature planning. This would be the case if the program needs to respond to a user while it's in the process of recovery. The user-facing behaviour will probably be determined in collaboration with a product manager, not just by the programmers.

Also, error recovery might be a large part of the code. As a made-up example, consider a back end that accepts network requests for product orders. A server might error while processing the order. To handle that scenario, you might do things like:

have an initial server record the order information so it's not lost.
have some recovery mechanism for the faulty server. E.g. some other process may restart it. Or, maybe the server can try to fix its own state internally.
the order can be given to a different server, or maybe the erroring server can try to process it again after it's fixed.

Here are some more examples of possible recovery mechanisms. If something in the code fails:

maybe you can try to manually fix or reset the state in the program.
maybe you can try running the operation again. If the problem is a race condition, it may work next time.
if it's a subprogram that's erroring, maybe you can restart it. If the problem is invalid state in the subprogram, then restarting it may work.
maybe you can have a backup program hosted on a server. If the client is producing incorrect results, then maybe it can call on the server to do the calculation instead.
maybe you can have a backup program with less features than the main program. If the main program is erroring, maybe run the backup program instead which only provides barebones operation.

Of course, if a critical part of the program is buggy then maybe you can't do anything about it in runtime. The only solution may be to fix the code.

You'll also need to have risk analysis. That's where you consider things like:

what code could have errors?
how likely it is that it will have errors?
what impact would the error have?
what would it cost to prevent the error from ever happening or to implement recovery mechanisms for that error?

The idea is that recovery will need to be considered as a first class citizen and a requirement during the project.

Note that these kinds of recovery measures are probably reserved for programs that really need defensive programming. For most normal programs, it's probably enough to simply restart a server or notify the user that something went wrong.

Downsides of defensive programming

Defensive programming has significant downsides. For example:

it requires a lot more code. At the very least, you'll have many more conditions and checks than a similar program without defensive programming.
performance can be worse. That's because the extra checks take time to execute.
it makes the code harder to work with because there is a lot more code.
error recovery can take a long time to plan for and implement.

When to use defensive programming

Whether or not you use defensive programming depends on your program.

As mentioned earlier, some programs need maximum availability, reliability and security. Those types of programs may require a lot of defensive programming.

For most other programs, you shouldn't need defensive programming. "Normal programming" should be enough. Nonetheless, you're free to use some defensive programming techniques around some key areas of the code. It's up to you to make the decision.

Regardless of what you do, remember to be pragmatic. Use risk analysis. Consider:

what could go wrong?
how much chance is there of it going wrong?
what would the impact be?
how could you prevent it from going wrong?
what would it cost to implement prevention or recovery?

Then, use the right amount of defensive programming where necessary. Try to avoid overusing defensive programming if it's not necessary.

Offensive programming

The goal of offensive programming is to catch bugs and crash early. As explained in how to respond to errors, crashing early is helpful.

It means that you are notified of bugs immediately. Also, the stack trace from the crash is closer to the source of the problem. This helps with debugging.

How to do offensive programming

To do offensive programming, you:

do normal programming
don't recover from bugs (avoid defensive programming)
write code in a way where bugs are obvious and easy to find
immediately crash the program on bugs

Just like with normal programming, you still need conditionals for things that aren't bugs. For example, you need conditionals for null checks.

Similarly, you should probably handle errors which aren't bugs. For example when users provide invalid data, or when you're not able to find a file in the file system. Most of the time, it would be unreasonable to crash on them. In other words, you should probably follow the "normal programming" way of dealing with these.

Also, you should write code in a way where bugs are easy to find. Here are some techniques for that.

Avoid fallback code and default values

Things like default state, default arguments and fallback code can hide bugs.

For example, you might call a function with incorrect arguments. You might have accidentally used null instead of a string for an argument. That's a bug. However, due to default arguments, the argument will be a string anyway. The bug won't be caught and the program may do the wrong thing as a result.

A similar thing applies to fallback code. One example is inheritance and subclassing. You may have forgotten to implement a method in a subclass. Then, you call the method and it executes the parent's method. That's unintended behaviour, which is a bug.

To prevent this, avoid using things like default state, default values and fallback implementations.

Avoid checks on code that will crash on errors

Sometimes, buggy code will crash on its own. You don't have to do anything extra. Leave the code as it is and let it crash.

For example, consider the code below. array should never be null. If it's null, that's a bug.

If you have a defensive check around it, the code won't crash:

function foo(array) {
  if (array !== null) { // code doesn't crash if array is null
    return array[0];
  }
}

But if you don't have a defensive check, the code will crash.

function foo(array) {
  return array[0]; // code crashes if array is null
}

You want the code to crash as early as possible. So, in this case, just leave it as it is without a defensive check.

Have conditionals or assertions to check for errors

Contrary to the point above, some bugs won't cause the program to crash.

For example, you might have some incorrect state in your program. Your program may not crash from that.

As another example, some code may execute that shouldn't execute under normal circumstances.

In these cases, you can use manual checks. Then, if you find something wrong, you can manually crash the program.

For example:

function foo(arg) {
  switch(arg) {
    case 'foo':
      // do something
      break;
    case 'bar':
      // do something
      break;
    default:
      // this code should never execute, so crash the program if it does
      throw new Error('Default case should never execute.');
  }
}

Here's another example with checking state:

function getCurrentPlayerHealth() {
  const health = player.health;
  if (health < 0 || health > 100) {
    // this condition should never evaluate to true, so crash the program if it does
    throw new Error(`Player health should be between 0 and 100.`);
  }
  // continue normal function execution
}

More traditionally, these kinds of "bug checks" use assertions instead of conditionals.

Assertions are bug-finding tools. If they fail, they signify a bug. Conditionals are control-flow tools. If a conditional "fails", it doesn't signify a bug. It means that a different block of code should execute instead.

So, instead of using conditionals, you can use assertions. For details on how to do that, please see the documentation for your programming language.

Here's a code example in JavaScript:

console.assert(player.health >= 0 && player.health <= 100, player); // logs a stack trace if condition is false, along with the player object

In some programming languages, assertions crash the program. However, in others, they don't crash it. They may only print an error message to the console or something. Both are usable. However, offensive programming recommends hard crashing when possible.

Also, some programming languages allow you to turn off assertions in production for better performance.

Downsides of offensive programming

Similar to defensive programming, offensive programming has downsides.

One downside is having to avoid certain kinds of code like default arguments. Default arguments have valid use cases. They provide "reasonable defaults". They can make some code much easier to work with.

Another downside is having to crash the program. As explained in how to respond to errors, crashing on bugs is usually good. However, it might be something that you're not prepared to do in your application.

Another downside is performance. Having assert statements throughout your code can significantly reduce performance.

As a result, many programming languages don't crash when assertions fail. Also, they have the option of removing assertions from production code. With this option, you lose the benefits of offensive programming in production. You only gain the benefits during development. However, that alone can be very useful.

When to use offensive programming

Offensive programming helps you catch bugs. That's a significant win.

For this reason, it's good to use it during development. Generally, you'll put assert statements here and there to ensure that certain things are correct.

As for production, it depends. Consider the pros and cons of offensive programming and make your decision.

It's alright to only use offensive programming in development. After all, catching more bugs during development is better than nothing.

Be pragmatic

When choosing your approach to handling errors, you need to be pragmatic.

"Normal programming" is the minimum that you need to do for most programs.

For some programs, you might use defensive programming. In particular, for programs that need high:

availability
security
reliability

But also understand the downsides. Primarily, the downsides are worse performance and longer development time.

Offensive programming helps you catch bugs. This is useful during development (and even production).

You can mix and match the approaches based on what you need. You can even use different methodologies in different areas of the code. It's up to you to decide.

Final notes

So that's it for this article. I hope that you found it useful.

As always, if any points were missed, or if you disagree with anything, or have any comments or feedback then please leave a comment below.

For the next steps, I recommend looking at the other articles in the error handling series.

Alright, thanks and see you next time.

Credits

Image credits:

Turtle in sea - Photo by Tanguy Sauvin from Pexels
Turtle in shell - Photo by Hogr Othman on Unsplash
Tiger - Photo by Samuele Giglio on Unsplash
Squirrel - Photo by Pixabay from Pexels

Nulls and null checks - How to work safely with nulls in any codebase

Spyros Argalias — Sat, 01 Jan 2022 14:24:28 +0000

An important part of clean code is handling nulls properly.

Nulls have been a tricky problem in programming for decades.

Tony Hoare, the inventor of the null even called it a billion-dollar mistake.

Semantically, nulls are necessary. They represent the absence of a value. For example, a user may fill in a form that has optional fields. They may leave the optional fields blank. That's one reason for nulls.

The problem is that nulls can be difficult to work with and track.

The problem with nulls

Nulls are hard to track in a codebase. There are many things which:

have properties that are null
can return null
need to check for null before doing something

If you miss a single "null check", you have a bug. Your program might do the wrong thing or even crash.

For example, here is some code that crashes if you forget to check for null first:

// this function crashes if the argument is null
function foo(arrayOrNull) {
  return arrayOrNull[0];
}

The code should have been like this instead:

function foo(arrayOrNull) {
  if (arrayOrNull === null) {
    return null;
  }
  return arrayOrNull[0];
}

The issue is that being 100% thorough with your null checks is very hard. It's extremely difficult, if not impossible, to keep track of every null.

Solutions for working with nulls

Working with nulls is difficult. To make things easier, here are some possible solutions you could use. Some of them are bad and some of them are good. We'll go over each one.

The solutions are to:

place a null check around everything
use try / catch instead of null checks
return a default value instead of null
use the null object pattern
remember to check for every null
use a programming language with a type system that can track null
use something like the Option type

Here is each one in more detail:

Place a null check around everything

One solution for dealing with nulls is to always check for them, even when you shouldn't need to. Check "just in case". After all "It's better to have it and not need it than to need it and not have it." - George Ellis. Right?

If this is your only way of ensuring that you don't miss null checks, then maybe...

However, it's not an optimal solution. The problem is that something in your code might be null when it's not supposed to be. In other words, you have a bug.

But, if you have null checks where they're not needed, you'll silently ignore the bug. It will be swallowed up in a null check.

For example:

// car is never supposed to be null
if (car !== null) {
  car.getWheels();
}

In the code above, car may be null when it's not supposed to be. That's a bug. However, due to an unnecessary null check, the program won't crash. The bug will be silently ignored.

But, if you didn't have the unnecessary null check, the program would crash.

For example:

// car is null due to a bug
// the program crashes
car.getWheels();

This is a good scenario. As explained in how to respond to errors, at the very least, you want to know that you have a bug. Crashing makes that clear, but silently ignoring bugs doesn't.

In other words, you should probably avoid unnecessary null checks.

Otherwise, if you want to do defensive programming, you can have the extra null checks. However, put in some code that records the bug if the thing is actually null. That way you can debug the problem later. (For more information please see record errors to debug later.)

Use try / catch instead of null checks

Conditionals vs try / catch is a debate that applies to all possibly invalid actions. For this reason, it's explained more thoroughly in control flow for invalid actions.

That aside, try / catch won't solve the problem.

You might forget to add try / catch blocks, just like you might forget null checks. In this case, your program could crash.

Worse, an exception might be caught, unintentionally, by a different try / catch block. That's a silent bug. Silent bugs tend to be worse than crashes.

Return a default value instead of null

Another option is to avoid returning null. Instead, return a default value of the relevant type.

For example, you might have a function that would normally return a string or a null. Instead of null, return the empty string. Or, you might have a function that would normally return a positive number or null. Instead of null, return 0 or -1 (if 0 isn't a suitable default).

Benefits of default values

Default values reduce the number of nulls in your code.

In some cases, they also reduce the number of conditionals. This happens when you can treat the default value and the "normal" value the same way.

For example, this code works whether user.name is a normal value or the empty string.

function printUserGreeting(user) {
  const name = user.name;
  const formattedName = name.toUppercase();
  const greeting = `Hello ${formattedName}`;
  document.body.append(greeting);
}

But, if user.name was sometimes null, the function would need a null check to work.

function printUserGreeting(user) {
  const name = user.name;
  if (name === null) { // null check
    document.body.append('Hello');
  } else {
    const formattedName = name.toUppercase();
    const greeting = `Hello ${formattedName}`;
    document.body.append(greeting);
  }
}

Returning default values can be good. However, there are downsides.

Downsides of default values

One downside is that the semantic meaning of null isn't being honoured. Semantically, null means the absence of a value. It doesn't mean a legitimate value. In comparison, the empty string or the number 0 could be legitimate values. 0 or -1 could be the result of a math calculation. The empty string may be a delimiter provided to a function. They don't mean the absence of data.

Another downside, related to the first, is that you lose information on whether the value represents null or a legitimate value. Sometimes it's important to differentiate between the two. You won't always be able to use the default value and a normal value in the same way.

For example, consider JavaScript's Array.prototype.indexOf() method. It returns either a natural number (0 or a positive integer), or -1 as a default value (instead of null). But, in most situations, you can never use the value -1. You'll need a conditional to see if the method returned -1 or a normal value. This defeats the point. From the point of view of your code, it might as well have been null.

For example:

function findUser(userArray, targetUser) {
  const index = userArray.indexOf(targetUser);
  if (index === -1) {
    console.log('Sorry, the user could not be found');
  } else {
    console.log(`The target user is user number ${index + 1}`);
  }
}

Another downside is that you might have many functions. Each might need a different default value. In this case, you'll have a default value that works for one of them, but not for the others. Then, the other functions will need conditionals to check for the default value. Again, this defeats the point. It actually makes the code harder to work with. Checking for null is easier than checking for "magic values".

Just to finish off, some other downsides are that:

coming up with a default value can be difficult
tracing the origin of a default value (in code) can be difficult

Verdict for default values

To summarize: This is a solution which can be helpful to use. However, be careful of the downsides. You'll need to use your own judgement for when to use this option.

Personally, I don't use it too often.

But, one "default" value that's often good to use is an empty collection. For example, an empty array, or an empty hashmap. This tends to have all of the benefits without the downsides. That's because it's semantically correct to say "yes, this thing has a collection, it just happens to be empty". Also, most code should be able to work with an empty collection in the same way as a non-empty collection.

Use the null object pattern

The null object pattern is similar to using default values (mentioned above).

The difference is that it works with classes and objects, rather than primitive values like strings and numbers and such. It sets defaults for values (attributes) as well as behaviour (methods).

You use the null object pattern by creating a null / empty / default object with the same interface as a normal object. The attributes and methods of this object would have default values and behaviour.

For example, here is a normal User class that you might have in your codebase:

class User {
  constructor(name, id) {
    this.name = name;
    this.id = id;
  }

  updateName(name) {
    this.name = name;
  }

  doSomething() {
    // code to do something
  }
}

Here is an example NullUser class that you might have (a null object):

class NullUser {
  constructor() {
    this.name = 'Guest'; // default value
    this.id = -1; // default value
  }

  updateName() {} // do nothing (default behaviour)

  doSomething() {
    // do nothing, or do some other default behaviour
  }
}

The usage in code would be something like this: You might have some code that would normally return either null or a normal object. Instead of returning null, return the null object. This is analogous to returning a default value.

For example, the code below sometimes returns null:

function findUser(userId) {
  const targetUser = users.find(user => user.id === userId);
  if (!targetUser) {
    return null;
  }
  return user;
}

Instead, you can have this code, which returns a null object instead of null:

function findUser(userId) {
  const targetUser = users.find(user => user.id === userId);
  if (!targetUser) {
    return new NullUser();
  }
  return user;
}

Then, whenever you use the null object or the normal object, you don't need a null check.

To illustrate the point, here some example code without the null object pattern:

// class User is shown above

const users = [new User('Bob', 0), new User('Alice', 1)];

function findUser(userId) {
  const targetUser = users.find(user => user.id === userId);
  if (!targetUser) {
    return null;
  }
  return user;
}

function printName(user) {
  if (user === null) { // null check here
    document.body.append(`Hello Guest`);
  } else {
    document.body.append(`Hello ${user.name}`);
  }
}

function main() {
  const user = findUser(123);
  printName(user);
}

Here is the same code, except it uses the null object pattern:

// classes User and NullUser are shown above

const users = [new User('Bob', 0), new User('Alice', 1)];

function findUser(userId) {
  const targetUser = users.find(user => user.id === userId);
  if (!targetUser) {
    return new NullUser(); // instead of returning null, return a null object
  }
  return user;
}

function printName(user) {
  // no null check
  document.body.append(`Hello ${user.name}`);
}

function main() {
  const user = findUser(123);
  printName(user);
}

As for whether to use the null object pattern or not, similar points apply as for default values.

Remember to check for every null

One way to be thorough with all of your checks is... to be thorough with all of your checks...

Every time you work on code, be extremely careful with your null checks. You should understand where null can appear and where it shouldn't appear (where it would be a bug).

It's very difficult. Sometimes it might feel impossible. But, that's what you have to do if you're not using other solutions.

Use a programming language with a type system that can track null

Type systems to the rescue.

Some static type programming languages are able to track null just like they can track any other type. Then, if something in the codebase could either be null or another type, they force (or warn) you to have a null check.

Some examples are:

C# with its nullable reference types
TypeScript when the strictNullChecks option is enabled
Kotlin's nullable reference types

Also, some of these languages have non-nullable types. They can prevent you from assigning null to a variable altogether. This gives you a guarantee that a variable will never be null, so you don't need a null check.

For example, using TypeScript (with strictNullChecks enabled):

let a: string;
a = 'foo'; // works
a = null; // doesn't work, you get a compilation error
let b: string = null; // doesn't work, you get a compilation error

In this case, that variable will never be null.

In summary, with some type systems:

you'll be forced, or reminded, to have null checks when you need them. This way, you can never forget a null check.
you can declare some variables as non-nullable. This means that they'll never be null. The type system will be aware of that and notify you.

Personally, I think that this is a great option.

(Credit to Nicolas Frankel for mentioning non-nullable types.)

Use the Option type

The final option (no pun intended) is to use something like the Option type (also known as the Maybe type).

This doesn't completely eliminate null checks. But, it reduces them a lot. Also, the few remaining null checks are in places where they're easy to work with. It's very difficult to forget to put them in.

With the Option type, you have two null checks instead of a countless number of them.

The null checks are in:

the Option type itself
the first function to return an Option type

Here's a (very) simplified implementation of the Option type:

class Option {
  constructor(nullOrNormalValue) {
    this._value = nullOrNormalValue;
  }

  map(fn) {
    if (this._value === null) {
      return this;
    }
    const newValue = fn(this._value);
    return new Option(newValue);
  }
}

To do something with the Option type, you use the map method and pass in a function. This should be familiar if you've ever used a map function for arrays and such.

The key point here is that the null check is inside the Option type. In other words, every single time you try to use that value, you get a null check for free. This means that, as long as you're working with the Option type, you can never forget your null checks.

You also need a null check, or some other conditional, in the place where you'll return an Option for the first time.

For example, here's a normal function that would normally return null or a normal value:

function getNextScheduledEvent(user) {
  if (user.scheduledEvents.length === 0) {
    return null;
  }
  return user.scheduledEvents[0];
}

Here is the same function, but now, it returns an Option.

function getNextScheduledEvent(user) {
  if (user.scheduledEvents.length === 0) {
    return new Option(null);
  }
  return new Option(user.scheduledEvents[0]);
}

After writing that code, you don't need any more null checks for the returned value.

For example, here's what the code would look like without Option:

function getNextScheduledEvent(user) {
  if (user.scheduledEvents.length === 0) {
    return null;
  }
  return user.scheduledEvents[0];
}

function foo(nextScheduledEvent) {
  if (nextSceduledEvent === null) { // null check
    // do nothing
  } else {
    // stuff
  }
}

function bar(nextScheduledEvent) {
  if (nextSceduledEvent === null) { // null check
    // do nothing
  } else {
    // stuff
  }
}

function baz(nextScheduledEvent) {
  if (nextSceduledEvent === null) { // null check
    // do nothing
  } else {
    // stuff
  }
}

function main() {
  const user = {scheduledEvents: []}
  const nextEventOption = getNextScheduledEvent(user);
  const a = foo(nextScheduledEvent);
  const b = bar(nextScheduledEvent);
  const c = baz(nextScheduledEvent);
}

Notice that every function needs a null check.

Here is the same code using Option:

function getNextScheduledEvent(user) {
  if (user.scheduledEvents.length === 0) {
    return new Option();
  }
  return new Option(user.scheduledEvents[0]);
}

function doubleEventPrice(event) {
  // no null check
  return {
    ...event,
    price: event * 2,
  }
}

function foo(event) {
  // stuff, no null check
}

function bar(event) {
  // stuff, no null check
}

function main() {
  const user = {scheduledEvents: []}
  const nextEventOption = getNextScheduledEvent(user);
  const a = nextEventOption.map(doubleEventPrice);
  const b = nextEventOption.map(foo);
  const c = nextEventOption.map(bar);
}

Notice the lack of null checks.

Of course, this is a very simplified explanation. There is much more to using the Option type. A real implementation of Option would also be more much more complicated.

Which option should you use?

We covered a lot of methods for dealing with nulls.

It's up to you to choose the appropriate one for your codebase. You need to weigh the pros and cons of each. You also need to consider your preferences.

Personally, I love the type system enforced null checks. Along with those, I might use default values or the null object pattern sometimes. As of the time of writing, I haven't used the Option type very much. However, many people are passionate about that one. It seems like a great solution.

If you want, leave a comment below about which method you recommend and why.

Final notes

So that's it for this article. I hope that you found it useful.

As always, if any points were missed, or if you disagree with anything, or have any comments or feedback then please leave a comment below.

Alright, thanks and see you next time.

Credits

Image credits:

Single box - Photo by Christopher Bill on Unsplash
Two boxes - Photo by Karolina Grabowska from Pexels
Sticky note - Photo by AbsolutVision on Unsplash
Pointing to laptop - Photo by John Schnobrich on Unsplash

Exceptions vs error values

Spyros Argalias — Wed, 29 Dec 2021 18:11:08 +0000

Exceptions vs error values has been a debate in error handling for ages. Some people have firm stances on them. For example, in the book Clean Code, Uncle Bob recommends exceptions. In his post on Exceptions, Joel mentions that he prefers error values.

Programming languages have also taken stances. Popular languages such as C# and Java traditionally use exceptions. Languages like Rust use error values.

In this article we'll examine some of their similarities and differences. We'll also provide suggestions about when to use which.

Basic examples of exceptions and error values

Just for a quick introduction, here are some examples of exceptions and error values.

If you're already familiar with them, then please skip to the next section.

Here's an example of throwing and catching an exception in C#:

public class Example
{
    public void Foo()
    {
        try
        {
            Bar();
        }
        catch (IndexOutOfRangeException ex)
        {
            // handle error
        }
    }

    public void Bar()
    {
        if (true /* some condition to check if something went wrong */)
        {
            throw new IndexOutOfRangeException("Some error message");
        }
        else
        {
            // normal program execution
        }
    }
}

In the code above, Bar throws an exception. The exception is caught and handled in Foo, in the catch block.

Here's the same thing in JavaScript:

function foo() {
  try {
    bar();
  } catch (error) {
    // handle error
  }
}

function bar() {
  if (true /* some condition */) {
      throw new Error("Error message");
  } else {
      // normal program execution
  }
}

Error values can be implemented in different ways. One way is for a function to return either an error or a normal value.

For example:

function foo() {
  const result = bar();
  if (result instanceof Error) {
    // handle error
  } else {
    // normal program execution
  }
}

function bar() {
  if (true /* some condition */) {
    return new Error('Error message');
  } else {
    return 42;
  }
}

In the code above, bar can return either an error or a normal value. foo checks the return value. If it was an error, it handles it. Otherwise, it continues normal program execution.

You can also use error values by returning a single object. The object should have fields for both the error and the normal return value. For example, you could use a tuple, or an object with properties. If there was an error, the value should be empty. For example {error: new Error('Message'), value: null}. If there wasn't an error, the error value should be empty. For example {error: null, value: 42}.

Here's a code example:

function foo() {
  const result = bar();
  if (result.error !== null) {
    // handle error
  } else {
    // normal program execution
  }
}

function bar() {
  if (true /* some condition */) {
    return {error: new Error('Error message.'), value: null};
  } else {
    return {error: null, value: 42};
  }
}

In the code above, bar always returns an object. If something goes wrong, the object will have a value in the error field. Otherwise, the error field will be null.

Similarities between exceptions and error values

Exceptions and error values are fairly similar. In fact, some newer programming languages such as Rust and Swift eliminate most of the differences between them.

The most important thing about both of them is that they act as different return values from a function / method. The different return values should lead to different code execution paths.

They also share a big downside. It's easy to mess up with both of them.

With an exception, you may:

forget to catch it
wrongly assume that some code higher in the call stack will catch it
accidentally catch it higher in the call stack in a place that's not prepared to handle it properly

Also, you can completely avoid checking error values.

It's very easy to forget or mess up. Even if you don't, someone else might. So, you have to be very diligent.

Or, you can use a programming language that forces you to check all errors. (More on that later.)

Differences between exceptions and error values

Exceptions and error values have some differences:

Performance

Throwing and catching exceptions are commonly considered slow. Returning error values is fast.

However, exceptions are supposed to be "exceptional" (thrown very rarely). In practice, this means that the performance of your application shouldn't be negatively affected by using them.

Crashing the program vs silent bugs

Uncaught exceptions crash the program. More rarely, exceptions can also result in silent bugs (if you catch them higher in the call stack without intending to).

Unchecked error values result in silent bugs.

Exceptions are better in this case. As explained in how to respond to errors, crashing the program is a better default option than silent bugs.

Bubbling

Exceptions can "bubble" up the call stack. An exception that's not caught in a catch block will be thrown in the caller (the previous code in the call stack). If it's not caught there, the process will repeat. If it reaches the end of the call stack, the program will crash.

Bubbling is both good and bad.

The benefit is that it's very convenient. You can have a single try / catch block in some parent function. The exception will propagate to it and will be caught there.

The downside is that the flow of execution is not explicit. You have to keep track of it yourself. You also have to remember which exceptions are caught where in the call stack.

This can put you into a bad situation. Sometimes you might not remember or know if an exception will be caught or not, or where it will be caught, or by what.

In comparison, error values are standard return values. If you want them to propagate, you have to propagate them manually. You have to manually return them across different functions / methods, all the way up the stack.

The benefit of this is that it's very explicit. It's very easy to track and reason about. The downside is that it's very verbose. You need many return statements across many different function / method calls.

Note that you can technically manually propagate exceptions if you want to. However, that's not common practice. For more details on this please see "checked exceptions" in a later section.

Suitability in functional programming

Generally, exceptions are less common in functional programming.

That's because functional programming promotes immutability and pure functions.

With exceptions, sometimes you need to break immutability. For example, often, you need to declare variables outside of try / catch blocks and then mutate them in try / catch.

Here's a code example:

let a;
try {
  a = new Something();
  // do stuff with `a`
} catch (error) {
  // handle error
} finally {
  a.close();
}

Also, thrown exceptions are not standard return values. This messes up the "pure function" point.

Exceptions and error values in some newer languages

Some newer languages, like Rust and Swift, change things up a bit.

Most importantly, they force you to check all error values and thrown exceptions. This means that you can never forget to check for errors or to handle exceptions.

In the case of Swift, it also makes exception bubbling more explicit. It still allows exceptions to propagate automatically. However, it requires intermediate functions (that an exception will propagate through), to be marked with the keyword "throws".

This additional explicitness makes exceptions easier to track throughout your code.

The downside is that it makes things more verbose.

(Rust uses error values, which you have to propagate explicitly anyway.)

Which should you use?

Overall, it seems like this is a question of robustness and amount of safety measures vs verbosity.

Enforcing error checking and having explicit error propagation have obvious benefits. It makes it much harder to forget to do your error handling. You'll have to intentionally ignore it to avoid it.

However, verbosity has downsides too. It can can make code less readable. It can also make it harder to make large changes to code. This can be especially prominent if you're propagating everything manually.

For example, imagine that you change a low-level function (or add a new one) to sometimes return an error value. That error may need to be handled at a higher-level function. This means that you'll need to add code to every intermediary function to keep propagating the error.

That's a large change. In comparison, if you added an exception that bubbled automatically, you would just add a try / catch block at the high-level function and you'd be done.

So it's up to you to decide where you stand on the safety measures vs verbosity scale.

For maximum safety measures, you should probably use a language that forces you to check all errors and forces explicit propagation of them. The downside is that the error handling will be more verbose.

One level lower in safety is to use error values. I regard these as more robust than throwing exceptions. That's because propagating error values is more explicit than bubbling exceptions. The downside is that there's more verbosity. Also, note that you need to be very diligent with these. If you forget to check an error, you'll get silent bugs. Unchecked error values are worse than uncaught exceptions.

Otherwise, go for throwing "normal" exceptions (such as the ones in Java, C# and JavaScript). They're the least verbose. This doesn't mean that you can't create robust programs with them. It just means that it's up to you to be diligent with errors and to track everything.

It's probably also a good idea to consider the convention in your programming language. Some programming languages prefer exceptions. Some others prefer error values.

My personal preference is to lean towards higher safety for larger scoped and more critical projects. For smaller scoped projects, I lean towards less verbosity and more convenience (exceptions).

Final notes

So that's it for this article. I hope that you found it useful.

As always, if any points were missed, or if you disagree with anything, or have any comments or feedback then please leave a comment below.

For the next steps, I recommend looking at the other articles in the error handling series.

Alright, thanks and see you next time.

Credits

Images:

Duelling Legos - Photo by Stillness InMotion on Unsplash
Typewriter and laptop - Photo by Glenn Carstens-Peters on Unsplash
Post-it notes - Photo by Will H McMahan on Unsplash

Best practices for error catching and handling

Spyros Argalias — Fri, 19 Nov 2021 17:41:19 +0000

Catching and handling errors is an important part of error handling.

Here are some best practices for it. Generally, it's good to:

be very thorough with your error checking
do your error checking first
handle errors at the earliest appropriate place
(for exceptions) put the minimum code you can in your try blocks
restore state and resources so the program can keep executing correctly

Here are the best practices in more detail.

(Note: For this article, "error" is defined in Terminology - Errors and non-errors. It means anything you might throw an exception or return an error value for. It doesn't just mean an "unrecoverable error".)

Be very thorough with your error checking

Unfortunately, programmers aren't perfect. We create bugs and make mistakes. In fact, we do that quite often. That's why we have so many error correction tools to help us.

So, in general, you should go by the assumption that everything in your program that can fail will fail. Other things that you didn't think of will also fail.

To minimise the issue, you should be very thorough with your error checking. Always catch all possible exceptions and check all error values. Then, handle them appropriately.

Check for errors first

This one is a stylistic convention.

In your code, it's good to do your error checking before anything else. Leave the normal program execution for after.

For example, in methods that throw exceptions, try to check for errors and throw the exception as early as possible.

Here's a code example:

class Example
{
    public void Foo(string a)
    {
        if (a.Length === 0)
        {
            throw new InvalidArgumentException("Parameter {a} must not be the empty string.");
        }
        // normal program execution
    }
}

Method Foo starts by doing its error checking. The normal code execution comes afterwards.

Avoid doing something like this:

class Example
{
    public void Foo(string a)
    {
        // do some "normal program execution" that doesn't need parameter `a`

        // check parameter `a` right before you need it
        if (a.Length === 0)
        {
            throw new InvalidArgumentException("Parameter {a} must not be the empty string.");
        }
        // more normal program execution
    }
}

In this code, Foo executes some code. Then, it does some error checking for parameter a.

The same principle applies to checking error values. Try to check for errors before you continue your normal program execution.

Here is a code example:

function foo() {
  const result = bar();

  if (result.error) {
    // handle error
  }

  else {
    // normal code execution
  }
}

The code above first checks for errors. Then, it continues normal program execution.

This organises your code into recognisable blocks. Errors first, normal code after. It makes your code easier to scan through and easier to understand.

It also helps with debugging. When an error is thrown, less normal code will have ran. This reduces the amount of code you'll have to check through when debugging.

Handle errors at the first appropriate place

Sometimes, you can't handle errors immediately. You might need to propagate them to higher level code.

To showcase this, consider this example: You have a function that searches the file system for a file. If it finds it, it reads its contents. Otherwise, it throws an exception. How should the code handle this exception? Should it:

crash the program?
create a new file?
search for a backup file in a different location?
notify the user that the file couldn't be found and ask them to try a different file?

The file system code doesn't know. Different programs will want different behaviour if the file isn't found. This means that the file system code can't have hardcoded behaviour to handle the exception.

Instead, the exception should be handled at a more appropriate place. The place that can decide what to do about it. Often, that means some code higher up in the call stack. So, the exception (or error value) needs to propagate up to that place.

For exceptions, that means that you should let the exception bubble up. Then, have a try / catch block at the place where you'll handle it.

For error values, you'll have to manually return them until they reach the correct place in the call stack.

Having said that, you should handle errors at the first appropriate place. Don't propagate them higher than necessary. The earlier you handle errors, the closer they'll be to the code that raised them. This makes the execution flow of the code easier to track and understand.

Here's a code example where we search the database for a record:

// server.js
import { getSpriteById } from './myDatabase.js';

app.get('/:spriteId', async (req, res) => {
  const spriteId = req.spriteId;
  try {
    await getSpriteById(spriteId);
  } catch (error) {
    // exception from database is handled here.
    // In this case, it responds with a 404.
    res.sendStatus(404);
    return;
  }
  res.send('Sprite found');
});

app.post('/foo', async (req, res) => {
  const spriteId = req.body.spriteId;
  try {
    await getSpriteById(spriteId);
  } catch (error) {
    // exception from database is handled here.
    // In this case, it redirects
    // to another page for the user to fill in correct information
    res.redirect('/form');
    return;
  }
  res.send('Data accepted');
});


// myDatabase.js
const db = await connectToDatabase('connectionString');

const getSpriteById = async (spriteId) => {
  // throws exception if it doesn't find the record
  const sprite = await db.findById(spriteId);
  return sprite;
};

export { getSpriteById };

(By the way the code is pseudocode, don't expect it to work if you actually run it. However, it showcases the point.)

In the example, the function getSpriteById searches the database. If it doesn't find the record it's looking for, it throws an exception. It doesn't handle the error itself. Instead, the handlers in server.js decide how to handle the error. Both handlers have try / catch blocks which handle the exception differently based on what they need.

(For exceptions) Be careful of how much code you put in your try blocks

It's considered best practice to put as little code as possible in each try / catch block. This means that you may need multiple try / catch blocks, instead of just one.

The benefits of this are that:

it's easy to see which code raises which exceptions (and which code doesn't raise exceptions)
it "separates concerns" more clearly. Each try / catch block is a separate piece of functionality. This makes it easier to refactor it into a separate function.
it prevents the accidental swallowing of exceptions. This happens if you put some code in try without thinking. That code might throw an exception that you weren't prepared to handle. However, it will be caught in catch (and potentially handled incorrectly). Then, the program will continue executing, potentially producing the wrong result.

It's also a solution for when certain lines of code can throw the same type of exception, but each case needs to be handled differently.

On the flip side, having small try / catch blocks can make the code more verbose.

In the end, you need to be pragmatic. Keep the benefits and downsides in mind. Then, make your decision. Usually, correctness and clarity are more important, even if they're more verbose. However, it's okay to make the code more concise sometimes, especially if you don't think correctness and clarity are too affected.

For example, this code could be separated further, but is still pretty good:

BufferedReader bufferedReader = null;
try {
    bufferedReader = new BufferedReader(new FileReader("path"));
    String line = bufferedReader.readLine();
    while (line != null) {
        doSomething(line);
        line = bufferedReader.readLine();
    }
} catch (FileNotFoundException | IOException e) {
    e.printStackTrace();
} finally {
    try {
        bufferedReader.close();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

Here is the same example separated more:

BufferedReader bufferedReader = null;
try {
    bufferedReader = new BufferedReader(new FileReader("path"));

    try {
        String line = bufferedReader.readLine();
        while (line != null) {
            // we’re leaving this line here for simplicity, but depending
            // on how it works, it might need its own try block
            doSomething(line);
            line = bufferedReader.readLine();
        }
    } catch (IOException e) {
        e.printStackTrace();
    }

} catch (FileNotFoundException e) {
    e.printStackTrace();
} finally {
    try {
        bufferedReader.close();
    } catch (IOException e) {
        e.printStackTrace();
    }
}

The second version would be necessary if each catch block needed to have different code. Otherwise, you can choose either version.

(The best solution is probably to use a with / using / try-with-resources statement, or the equivalent for your programming language. It automatically closes the bufferedReader at the end. The code above is just to showcase the point.)

Restore state and resources

If you successfully handle an error, then the program should be able to continue executing correctly. It should continue almost as though the error never happened.

This means that you need to:

restore state to something correct
close any side effects that were started by erroring code

Restore state

After recovering from an error, your program needs to have the correct state. If it doesn't, then you haven't really recovered.

This means that you might need to fix or restore your program's state in your error handling code.

Here's an example.

Consider that you have a Boolean variable. The Boolean variable should start as false. However, while some code is running, you set it to true. At the end, you set it to false again.

But, if the program errors at some point, the variable won't be reset. This will leave your program in a bad state, even if the error is handled.

Here's an example of some "dangerous code", which will have invalid state if an error occurs:

let isBusy = false;

async function handleUserEvent(event) {
  if (!isBusy) {
    isBusy = true;
    // do something asynchronous which may throw an exception, for example:
    // await doSomething()
    isBusy = false;
  }
}

If handleUserEvent errors, the value of isBusy will remain false forever. handleUserEvent won't be able to run properly again.

For that reason, you need to manually reset the state if an error occurs.

Here's a code example:

let isBusy = false;

async function handleUserEvent(event) {
  if (!isBusy) {
    isBusy = true;
    try {
      // do something asynchronous which may throw an exception, for example:
      // await doSomething()
    } finally {
      isBusy = false; // fix the state
      // exception is sent higher up because there's no catch block
    }
  }
}

// equivalent example
async function handleUserEvent(event) {
  if (!isBusy) {
    isBusy = true;
    try {
      // do something asynchronous which may throw an exception, for example:
      // await doSomething()
    } catch (error) {
      isBusy = false; // fix the state
      throw error;
    }
    isBusy = false;
  }
}

In this example, if an error occurs in handleUserEvent, there's no problem. The state is restored and handleUserEvent will execute correctly afterwards.

The same principle applies across all of your code in the call stack. Imagine that an error occurs in function bar. But, you handle the error in function foo, which is 5 function calls earlier in the call stack. For the program to be in a valid state, you need to make sure that you've fixed all of the state from bar to foo.

Basically, it means that you may need many intermediate try / catch blocks in different functions in the call stack. You fix the state in each one. That way, if the error is handled higher up, the state of all the intermediate code has been fixed. They can run again as though nothing went wrong.

For example:

// handleUserEvent
import foo from './foo.js';

// this is the top-level function
async function handleUserEvent() {
  try {
    await foo();
  } catch (error) { // handle the error at the top level
    // record error
    // display message to user that action didn't work
  }
}


// foo.js
import bar from './bar.js';

let isBusy = false;

async function foo() {
  if (isBusy) {
    return;
  }
  isBusy = true;
  try {
    await bar();
  } finally {
    isBusy = false; // restore this module's state
    // exception is sent further up because there is no catch block
  }
}

export default foo;


// bar.js
let isBusy = false;

async function bar() {
  if (isBusy) {
    return;
  }
  try {
    // do something asynchronous which may throw an exception, for example:
    // await doSomething()
  } finally {
    isBusy = false; // restore this module's state
    // exception is sent further up because there is no catch block
  }
}

export default bar;

(Yes, I know the code in the examples is very contrived, but hopefully it illustrates the point 😅)

Close side effects

Some side effects come in pairs. For example, if you open a file, you should also close it. It can be unsafe to leave it open.

So, make sure that resources like that are properly released.

If you use exceptions:

use with blocks. These automatically close resources if an error occurs. Some examples are with in Python, try-with-resources in Java or using in C#.
otherwise, use finally blocks (or their equivalent in different programming languages)

If you're using error values, place the "closing" code somewhere appropriate. It should run both in the error case and the non-error case.

Here's an example with finally:

// pseudocode

let file;
try {
  file = openFile('foo.txt'); // open the resource
  writeToFile(file, 'bar');
} catch (error) {
  // code to handle exceptions
} finally {
  close(file); // close the resource
}

Here's an example with error values:

// pseudocode

const [fileError, file] = openFile('foo.txt');
if (fileError) {
  // handle error
  close(file);
  return;
}
const [writeError, _] = writeToFile(file.value, 'bar');
if (writeError) {
  // handle error
}
close(file);

Final notes

So that's it for this article. I hope that you found it useful.

As always, if any points were missed, or if you disagree with anything, or have any comments or feedback then please leave a comment below.

For the next steps, I recommend looking at the other articles in the error handling series.

Alright, thanks and see you next time.

Credits

Image credits:

Net - Photo by Raghavendra Saralaya on Unsplash
Arrow - Photo by Hello I'm Nik on Unsplash
Squirrel in treehouse - Photo by Joakim Honkasalo on Unsplash

Error recording - How to record errors in your application to debug later

Spyros Argalias — Tue, 09 Nov 2021 13:48:53 +0000

Recording errors is an important part of error handling. In short, when certain errors occur in programs, you want to know about it. This is particularly important with bugs.

You need to:

know that they occurred
have useful information about them so you can debug them later

One way to do this is to use an error monitoring or logging service. Some examples are New Relic and Splunk. These will automatically record any program errors and such.

In particular, logging is very useful. It records a lot of information about what's happening in your program. This can help a lot with debugging.

Alternatively, you can manually record information about errors.

How to manually record errors

The goal is to be able to view errors later. You can achieve that in any number of ways.

One way is to manually record errors in a database.

To do this, you can:

prepare your database for recording errors
set up some code to record errors to the database
set up a global error handler to catch errors. (This error handler would call the code from step 2)
set up an endpoint in the back end so the front end can record errors too. (This endpoint would call the code from step 2)

For example, you might use a MongoDB database with a collection for errors. Every time an error occurs in your application, add information about it to the collection. You can organise the information in any way you like. For example, you could organise by the type of error or exception, by the error message, or by the last code in the call stack for the error.

After setting that up, you could set up a global error handler. This error handler would be called on errors that occur in your application. In the handler, record the error in your database.

Different frameworks and "environments" provide different ways to set up global error handlers. For example, in the Unity game engine, you can use Application.logMessageReceived += Handler;. On the front end of a website, you can use window.addEventListener('error', handler);.

Finally, you can set up an endpoint so that the front end can record errors too. Then, the front end can make a network request with information about the error it encountered.

Here's an example call you could make from the front end:

function handleError(errorEvent) {
  const {error} = errorEvent;
  const data = {stack: error.stack, message: error.message, type: error.name};
  fetch('https://example.com/errors', {method: 'POST', body: JSON.stringify(data)});
}
window.addEventListener('error', handleError);

The function handleError above is executed any time an error occurs. It creates an object with useful information about the error. Then, it sends a network request to the back end. The back end will then record the information about the error so it can be viewed later.

What information to record

You want as much useful information about the error as possible. This will help you debug it later.

The article .NET best practices on exceptions has some guidelines for this. Adapted for both error values and exceptions, they are to:

use the predefined error types in your programming language if they're relevant. Only create custom types if the predefined ones don't apply.
if you create custom error types:
- they should usually be subclasses of the main error types (if you use an OOP language)
- they can optionally have custom properties (if they would be useful)
use grammatically correct error messages. For example 'The file "foo.txt" could not be found.'.
include a localised string message in every error (if your application is localised)

Final notes

So that's it for this article. I hope that you found it useful.

As always, if any points were missed, or if you disagree with anything, or have any comments or feedback then please leave a comment below.

For the next steps, I recommend looking at the other articles in the error handling series.

Alright, thanks and see you next time.

Credits

Recording photo - Photo by Krists Luhaers on Unsplash

How to respond to errors - Crashing, ignoring, recovering and their use cases

Spyros Argalias — Tue, 02 Nov 2021 15:35:27 +0000

What should a program do when it encounters errors? In my experience, a lot of programs hardly give any thought to this. Usually it's just the bare minimum of silently ignoring bugs and maybe recording that they occurred.

However, this is an important consideration in error handling. A program should behave correctly when errors occur.

In this article, we'll examine:

possible responses to errors
examples of error responses in common programs
how to handle bugs in your program
how to handle other errors in your program

Let's dive in.

Response options

There are different ways that you can respond to errors. You can:

crash the program
silently ignore the error
try to recover in some way

Crashing the program is a good default option. There are multiple benefits to it.

One benefit is that the program won't be doing the wrong thing. There have been multiple situations where software doing the wrong thing has been disastrous.

This doesn't mean that crashing is good. It means that it's probably better than silently ignoring bugs. For example, it's fine for a calculator program to crash. You can just restart it and continue what you were doing. But, if a calculator has errors and produces the wrong result, that can be a big problem.

Another benefit to crashing is that it makes errors obvious. This means that you can debug the problem immediately.

In addition, crashing as soon as possible means that the stack trace will be more helpful. It will point to the problem code. Instead, if you silently ignore the error, the program may not crash until later (if at all). At that point, it won't point to the real source of the error. This means that debugging will be harder.

Another option is to silently ignore errors. Sometimes, this option is good. It depends on the user experience. Later on, we see a few examples where ignoring the error is probably the best option.

The final option is to try to recover from the error in some way. The result should be as though the error never happened. The program should be able to continue executing correctly.

Examples of responses to errors

Here are some examples of how different programs may respond when encountering errors.

A program that's in early development

If a program is in early development, it's probably fine to just crash on errors. This will make debugging easier.

Most desktop applications

Most desktop applications crash when something goes wrong (if they can't recover in the background). This is usually fine. It's very easy for the user to start the program again.

For programs that are "viewers" (such as Windows Photos), no data is lost.

For programs which change data (such as Microsoft Word), very little tends to be lost. These programs tend to have autosave features to minimise lost data.

Error on "add to cart"

Consider that you have an ecommerce website. There could be an error in the "add to cart" button where sometimes the product isn't being added to cart.

How should that error be handled?

For starters, you probably want to notify the user. It would be very bad if the user doesn't realise that a product is missing from their cart. They might go through checkout and order everything, wait for the item to arrive and never receive it. (I mean, I've done that without any errors to "add to cart" and I can tell you it's bad...)

To notify the user, you could display a message to them. For example, you could tell them:

the action failed
that they should try again later
that they should refresh the page and try again

A simple animation

Consider that you have a simple website with a small animation that you trigger with JavaScript.

For this website, if the animation fails to trigger, it's probably not a big deal.

In this case, you essentially want to ignore the error silently. Don't notify the user that a problem occurred. The animation isn't important enough to notify and distract the user from what they're doing.

A single player video game

If there is a bug in a single player video game, it probably doesn't matter. In most cases, it's very bad for the user experience for the game to crash. Having buggy gameplay is preferred to crashing. In this case, the best option is probably to silently ignore the bug.

An important system in an airplane

For something life-critical, you would want to recover from errors very carefully and deliberately.

This might mean having redundancy. For example, you might have backup systems so that one can take over if something goes wrong. Or you might have a live-monitoring program, which can restart and reinitialise other programs that have errored or crashed. Or any other number of things. You might also use defensive programming to prevent certain programs from failing in the first place.

How to handle bugs

A bug is when something unexpected or obviously wrong happens in your program. It arises from faulty coding. It wouldn't be there if the code was correct.

When handling bugs (or any error), you need to consider:

whether the bug is recoverable or not
the user experience
the development time for different responses

Also, regardless of what you do, you should record errors to debug them later.

Is the bug recoverable (without crashing)?

Some bugs are impossible to recover from. For example, there's nothing you can do if some important code always fails. The only solution is to fix the code.

However, some bugs may be recoverable.

One example of possibly recoverable bugs are intermittent bugs. These are bugs that only occur under certain circumstances. This includes race conditions or errors that only happen with specific state.

With some effort, you may be able to handle these without restarting the main program. For example, if an operation fails, you could:

try to run the operation again. If the problem is a race condition, it may work next time.
try to restart a faulty subprogram in the background. Then retry the operation afterwards.
try to manually fix the state of the program to something that works
offload the erroring operation to a server

Another example may be something like running out of memory. Even this can be recoverable sometimes.

However, one issue is that you may not know that your program has a particular bug. After all, if you knew about the bug, then the best solution would be to fix it. So, if you don't know about the bug, you might not have error handling for it.

The exception is if you're doing defensive programming. In this case, you'll have error handling "just in case". You won't actually know of whether you have a bug or not. Instead, you'll implement error handling pre-emptively for all kinds of possible bugs.

So, in summary:

some bugs aren't recoverable
some bugs are recoverable but you won't have error handling for them
some bugs are recoverable and you'll have error handling for them

The user experience

As shown in the examples above, different programs need to respond to errors differently. Sometimes, it's fine to crash the program. The user can restart it or another process can restart it automatically. At other times, you can silently ignore the error. In other cases, you may need to do everything in your power to recover.

Effort in implementing different error responses

In general, even though some bugs are recoverable, recovery can be extremely difficult. Some of the issues with it are explained in defensive programming.

In comparison, crashing the program is very easy. Also, this usually fixes errors just as well (if not better) than manually recovering.

Summary of handling bugs

Generally, when you encounter bugs, the rule of thumb is to crash the program. The most important reason for this is because defensive programming can be very difficult to implement.

At other times, it's okay to ignore the bugs. For example, when the area of the codebase that errored is insignificant.

Recovering from bugs is rare. It's only reserved for defensive programming. Defensive programming is mostly used for software where uptime and correctness are extremely valuable.

Finally, regardless of what you do, remember to record errors to debug them later.

How to handle other errors

"Other errors" are things which aren't bugs in your program. These can include things like:

failing to send a network request because the network connection dropped
failing to read a file from the filesystem because the file was deleted by the user, manually, a few milliseconds ago

These "errors" are normal and expected. They are things that any program may encounter. There is nothing that your program can do to completely prevent them.

Once again, you need to consider:

whether the error is recoverable or not
the user experience
the development time for different responses

In general, many of these errors are both recoverable and easy to recover from.

For example, consider that a network request failed to send because the user lost internet connection. It's relatively easy to show the user a message. Then, you can ask them try again after ensuring they're connected to the internet. This also results in a good user experience. In comparison, crashing the program would be a very bad user experience.

As another example, you might try to write to a file that doesn't exist. In this case, an appropriate and easy solution might be to create the file first.

So, overall, the common advice for these errors is to handle and recover from them. Of course, the details depend on your program. Some of these errors may be unrecoverable. In this case, crashing the program may be a better option.

Final notes

So that's it for this article. I hope that you found it useful.

As always, if any points were missed, or if you disagree with anything, or have any comments or feedback then please leave a comment below.

For the next steps, I recommend looking at the other articles in the error handling series.

Alright, thanks and see you next time.

Credits

Image credits:

Signs photo - Photo by Alexander Schimmeck on Unsplash
Jenga photo - Photo by Michał Parzuchowski on Unsplash
Person photo - Photo by Sebastian Herrmann on Unsplash
Chess photo - Photo by Nothing Ahead from Pexels

Naming (in code) - The ultimate guide and reference

Spyros Argalias — Mon, 21 Jun 2021 15:04:27 +0000

Programming principles tell us that naming in code is important. This article aims to be a complete learner's guide for naming in code. It also aims to be a reference about naming that you can refer to in the future if you need to.

For certain things, such as naming methods, there are different naming conventions. We'll mention a few so that you're aware of how they work and the options you can choose from.

Overall, we'll examine:

the motivation for wanting good names
general naming tips for all code
established naming conventions for specific things such as variables and classes

Motivation for good names

The motivation for good names comes from clean code and programming principles. Code should be:

immediately obvious and easy to understand
easy to change

Being easy to understand helps because:

code that's easy to understand will be faster to understand. This means that you can work faster. You'll spend less time trying to understand old code and more time writing new code.
code will be possible to understand. In comparison, if some code is difficult to understand, you may not understand it even after spending a long time reading it. Someone who's less experienced may have even worse luck. Additionally, you may misunderstand how the code works, especially if you're not fully paying attention that day. Misunderstanding code makes it very easy to create bugs.

Good names help with both cases.

How good names make code faster to understand

If something is well-named, then you don't need further details to understand it. This saves you time.

For example, consider:

a function named printHelloToTheScreen
a function named multiplyBy2
a constant named PI
a constant named MAXIMUM_ALLOWED_LOGIN_ATTEMPTS
a static class or module named Math
a variable named circumference
a variable named userInfo

In a codebase, you would have a pretty good idea of what those do just from the name.

How good names make code easier to understand

When reading code, you have to:

read (parse) what it does
understand why it does it, or rather, understand what it's trying to do conceptually

For example, it's not enough to think "this code removes initial whitespace from the string, then it sends a network request". Instead, you have to understand "this code formats the username and then sends a password reset request".

Here's a code example that's difficult to understand:

function foo(a, b) {
  const c = PI * a ** 2 * 8 / b;
  return c > 1 ? c : 1;
}

What's the 8 there for? What's b? Why does it return a minimum of 1? What's the purpose of this function?

If you're trying to do something such as change the area, you don't know if this function is relevant or not. Even if you suspect it is, you don't know what it does or why.

Something like this would be much better:

function calculateRemainingArea(radius, reductionFactor) {
  const area = PI * radius ** 2;
  const remainingArea = area * AREA_REDUCTION_RESISTANCE / reductionFactor;
  return Math.min(remainingArea, MINIMUM_AREA);
}

So, good names help, because they provide meaning. They help you understand what the code does and why it does it.

To get the benefit, all you have to do is give a good name to the thing.

As another example, someone may not understand PI * a ** 2. They may think "PI, a, power of 2... What the heck is that??". To make it easier, all you have to do is replace that line with const circleArea = PI * radius ** 2. It helps a lot.

General naming tips for code

In short, a good name is something that immediately tells you what something is or does. It's not surprising. It doesn't take effort to understand it. You understand it without thinking about it.

A bad name is something that you read and you wonder "what's that", or "what does that do?". Something that requires you to think more.

When writing names, they should be understandable by someone that's never seen this code before. They need to make sense, be consistent and be sufficiently descriptive.

Here are some pointers to accomplish this.

Have clear naming conventions

Your codebase should have clear conventions. This is probably the most important point in this article. If you're already following a convention, it's probably best to stick to it, even if an alternative may be more descriptive.

Conventions apply consistency. Programming principles tell us that consistency is very important.

It allows you to work faster. You can make certain assumptions about how the code works and what certain things mean. Additionally, when thinking of a name for something, the convention may already have a rule for it. This makes things easier.

Also, not following conventions can cause mistakes. You may assume that a common convention is being followed in the codebase. If you're wrong, then you may have the wrong idea about how some code works. At that point, it's very easy to create bugs.

Ideally, you should follow conventions that already exist in your programming language or framework. This makes things easier for new developers to the company. Some examples are the .NET naming guidelines and Airbnb JavaScript style guide. Otherwise, you can also create your own custom conventions for your project or company.

Prefer descriptive names

Always consider, will the next person who looks at this name understand it easily?

Use full words

Generally, full words are easier to understand. For example calculateArea or createWindow. Abbreviated words may be harder to understand. In general, avoid names like calcArea or cWin.

Avoid very short variable names

In particular, avoid single-letter or very short variables, such as d. It could mean anything: the document, data, date, or days.

The exception to this is when the name is used in a very small scope and what it represents is immediately obvious. In this case, it's easy to look one or two lines up and see where it was defined. Here's a code example using the variable e.

function sendData() { /* sends a network request */ }
function handleFormSubmission(e) {
  const formElement = e.target;
  const formData = FormData(formElement);
  sendData(formData);
}

Here, the variable e represents the event object. We know this because the name handleFormSubmission and the function signature represent an event handler. e is only used one line under where it is defined, so it's still easy to work with.

Nevertheless, I would still personally use event. I consider readability more important than minor saving of keystrokes like that.

Another acceptable example is using i in for loops and such. That's a convention that everyone understands.

Acronyms

If an acronym is very common, then it's okay to use it. Some examples are the acronyms HTML, UI, IO, OS, JSON, XML, HTTP.

If an acronym is uncommon, then prefer the fully expanded name. If in doubt, you should probably use the full version.

Conciseness matters

Names that are sufficiently descriptive come first. However, that doesn't mean that you need super long names.

Super long names, such as a variable named integerNumberOfEnginesInObject are difficult to work with. engineCount would be sufficient.

In general, if you can have the same clarity with a shorter name, use the shorter name.

Consider the context

The name of the surrounding context can provide useful clues for the purpose of something. This means that sometimes, you can get away with using shorter names.

For example, if you have a class called Users, then the method for creating a new user can be called create. The usage of it would be something like users.create() (where users is an instance of Users). That's sufficiently descriptive. You don't need to call the method createUser in this case.

Casing

The prevalent casings in programming (excluding HTML and CSS) are pascal case, camel case and snake case. The one you use depends on the conventions for your programming language or framework.

General format of each casing

Snake casing is lower cased and uses underscores to separate words. For example this_is_snake_case.

In pascal casing, every word begins with a capital letter. For example ThisIsPascalCase.

Camel casing is similar to pascal casing, except that the first word begins with a lowercase letter. For example thisIsCamelCase.

Casing for acronyms

For acronyms, the conventions vary.

On the front end, it seems that acronyms are always fully capitalised, regardless of length. Some examples are performance.toJSON(), XMLDocument, HTMLCollection and DOMString.

However, in some other languages, such as the .NET languages, the convention is:

if an acronym is only two letters long, the second letter should have the same casing (upper or lower case) as the first one. For example, UIInput (pascal case), uiInput (camel case) and fooUIInput.
if an acronym is three letters or longer, only the first letter should be capitalised if necessary. For example JsonFoo (pascal case), jsonFoo (camel case).

Capitalisation for compound words

It's a convention to treat compound words as one word in terms of capitalisation. For example, use callback and endpoint instead of callBack and endPoint. You can find a thorough list of common compound words, used in programming, on the .NET naming guidelines on capitalisation.

Prefer semantic naming

Semantic naming means to name something after its purpose or meaning. In order of priority, this means:

what the purpose of it is, or what it does
how it does it

As a bonus, it also results in code that is less likely to change in the future.

When naming things, consider: what's the most important thing about the thing you're naming? What's the most suitable name for someone else to understand it conceptually?

Usually, users care more about what something is doing, rather than how it's doing it. Although, sometimes, it's the "how" that's the most important.

Here are some examples of semantic naming.

Example with a variable name

If you have a variable that holds a collection of users, the important part is that it contains users. Whether it's a list or a map is less important. Not to mention that your IDE and type declarations provide that information anyway.

Therefore, the name:

users would be suitable
userList is less preferable. The "list" part is less important than the users part. Also, if you change the data structure in the future you'll have to update the variable name.
userCollection is also less preferable, because the "collection" part is less important than the "user" part. However, at least you won't have to update the variable name if you change the data structure in the future.

Example with interfaces and implementations

In OOP code, you tend to have interfaces with potentially multiple implementations. An interface may be called something semantic and generic, such as Sorter, for a sorting algorithm. That's the significant thing about it, the fact that it sorts. The how isn't important at the interface level.

The different implementations can be called after the sorting algorithm they implement. That's the important thing about them and the only thing that separates them from one another. It's the information a user of that specific class would want. For example BubbleSort, MergeSort, Quicksort.

Example with a method for sorting

Imagine that you have a class containing a collection of something. You also have a method for sorting it, say, alphabetically.

If you only have one sorting method, then it would be preferable to name it sort. A name such as sortWithQuicksort or quicksort would be unnecessary information that the user doesn't care about. If you think about it, the caller of the code wants to sort. They aren't particularly interested in the specific algorithm your class uses. (The only exception is if your class is an actual bottleneck to performance or something, but that's a different topic.)

Additionally, in the future, you may change the sorting algorithm that the class uses to merge sort. In that case, the name sortWithQuicksort wouldn't make sense any more.

The solution is to name your public method sort.

The fact that you're using quicksort is still important. Developers working on the implementation of the class would want to know that. Some options for that are to have a private method named quicksort, or import and use a quicksort function from somewhere else in the codebase.

For example:

// pseudocode

class Users
{
  // the public method with a name that's useful to callers
  public User[] Sort()
  {
    return _quicksort(this.users);
  }

  // the private method with a name that's userful to someone working on this class
  private T[] _quicksort<T>(T[] items)
  {
    /* implementation of quicksort */
  }
}

Example with front end CSS

In front end CSS, there are a few approaches. The approach you choose decides what's important about the name of your class.

When using the BEM naming convention, the important thing is the purpose of the element, not the styling. For example, you would use the CSS class page-heading instead of large-heading-red. That's because, tomorrow, the styling of the page heading may change. At that point, the non-semantic name won't make sense anymore, but the semantic name will.

If you're using a UI component library, then the styling of the component is more important than the purpose of the component. For example button-primary instead of add-to-cart-button. That's because classes like button-primary are the main ones you'll be working with throughout your code.

Other tips from Uncle Bob

Some tips that are mentioned in Uncle Bob's book Clean Code are to:

make meaningful distinctions. Avoid variables that seem similar or the same, such as accountInfo or accountData. A user of that code won't be able to tell the difference.
use pronounceable names. Names should be easy to read out loud. Some examples to avoid are names such as genymdhms and modymdhms. Better names would be generationTimestamp and modificationTimestamp.
use searchable names. Names should be easy to search using your code editor. Essentially, avoid names that are one or two letters long, as searching for them will return too many matches.
avoid using cute / offensive words. Avoid names such as whack() and seeYouLaterFiles(). Be professional and consistent.
pick one word per concept. For example, don't mix the words "fetch", "get" and "retrieve" for the same kind of operation throughout your codebase. Pick one of them and use it consistently.
avoid puns. Avoid using the same word for different concepts. For example, if in one class add() adds two numbers, in a different class add() shouldn't insert into a list.

Other tips from the .NET naming conventions

.NET makes some additional recommendations. Some of them are specifically for .NET languages. However, you may want to keep them in mind anyway.

The recommendations are to:

prefer naturally readable names. For example, use HorizontalAlignment instead of AlignmentHorizontal.
avoid using names that conflict with common keywords in other programming languages
prefer semantic names rather than language specific names. For example, use GetLength instead of GetInt.
prefer generic CLR type names instead of language-specific names. For example name a method ToInt64 instead of ToLong. That's because methods like these may be used in other CLR-compatible languages where the data type long doesn't exist. Therefore, that name won't make sense in those languages. However, Int64 exists and makes sense for all CLR languages.

Naming conventions for specific use cases

Here are some common naming conventions for things such as variables, functions, classes, etc.

Variables

Variables are just names or labels for values and objects. Some general conventions for them are that:

they should be nouns. For example car, user, userLocation, student, result, area, player
they generally use camel case or snake case, depending on your programming language

The rules change a bit for constants and variables holding Boolean values.

Constants

Some programming languages write constants fully capitalised and with snake case. This includes JavaScript, Python and Java. Some example constants are:

Number.EPSILON
Math.PI
NUMBER_OF_LIVES
MAX_ATTEMPTS_BEFORE_LOCKOUT
SOME_SPECIAL_VALUE

Here, "constant" refers to special values. These are values that don't depend on runtime. They could easily be placed in a configuration file, away from your application code.

"Constant" doesn't refer to a normal local variable that just happens to be immutable. Those follow the same conventions as normal variables.

Here are some examples of "constants" and "normal variables that just happen to be immutable":

final MAX_ATTEMPS_BEFORE_LOCKOUT = 5 (this could be in a configuration file, it's a special constant)
final float result = SomeClass.factorial(someNumber) (this is just a local variable that happens to be immutable. It varies at runtime depending on someNumber. It can't be placed in a configuration file)
const URL_ENDPOINT = '/ajax/foo' (this could be in a configuration file, it's a special constant)
const filteredArray = array.filter(a => !a) (this is just a local variable that happens to be immutable. It varies at runtime depending on array. It can't be placed in a configuration file)

Booleans

For variables that have Boolean values, the convention is to phrase them as a question. Start them with a predicate such as "is", "has", "had" and "can". These clearly denote that the variable holds a Boolean.

Some example Boolean variables are:

isValid
isComplete
isActive
isDisabled
isLoading
hasRan
hasArrived
hasDescendants
canTakeDamage
canDrive

In addition to being readable standalone, they read nicely in conditional statements:

if (hasLoaded) {
  doSomething();
} else {
  doSomethingElse();
}

In comparison, if you don't use a predicate, you would use a name such as complete. This is both a verb and an adjective. It can denote a number of things. It could be a function that you run to complete something, or a variable that holds things that have already completed, or a Boolean that states whether something has completed or not, or an event name. What it represents is more ambiguous, so prefer predicates instead.

A verb like completing is slightly better. It can't denote a function, because the "ing" in "completing" means that something is already happening. It's not something that you can start running now (like a function call). However, it can still be any of the other options. Overall, it's still preferable to use predicates.

Functions

Functions are units of code that do something. Conventions for function names are that:

they should be verbs
they generally use camel case or snake case, depending on your programming language

Some example function names are:

createReport
createTodo
getX
divide
sendRequest

For functions that return a Boolean, a common convention is for them to start with a predicate. This is similar to variables that contain Boolean values.

Some example names for functions that return Booleans are:

isValid
hasSignedIn
isSignedIn
isFormatted
canDrive

Another convention I've seen is for "transformer" or "converter" functions. These are functions that convert from one thing to another. They usually begin with "to", followed by the type they're converting to.

Some examples of transformer function names are:

toLowerCase
toUpperCase
toArray
toString

Classes

Classes are units of code that contain methods and attributes.

Some conventions for classes are that:

they use Pascal case
they should be nouns (or noun phrases)

Some example class names are:

Observable
Student
Printer
Player
ImageSprite

General property names

In general, attributes are named similarly to variables. Methods are named similarly to functions.

However, as mentioned earlier, the name of the class provides some context.

This means that you may be able to use a less specific name for a method / attribute than you would use for the equivalent function / variable.

For example, inside a class Users, you may have a method named create. The usage of it would be something like users.create() (where users is an instance of Users), which is sufficiently descriptive.

Casing and prefixing for properties

In terms of casing and prefixes, different languages and frameworks have different conventions.

For example, the Java naming conventions mention that methods and attributes should be camel cased.

The PEP 8 Python naming convention also mentions camel casing. However, it adds that private properties should be prefixed with an underscore. For example (_privateProperty).

The C# coding conventions seem the strictest. They state that:

public properties should be pascal cased (for example PublicMethod or PublicVariable)
private or internal properties should be prefixed with underscore and be camel cased (for example private void _privateMethod)
private or internal static properties should be prefixed with s_ and be camel cased (for example private static foo s_workerQueue)
private or internal thread properties should be prefixed with t_ and be camel cased (for example private static foo t_timeSpan)

If, for whatever reason, you were creating your own convention, I would personally recommend:

pascal casing for methods and camel casing for attributes (this is the convention used in the Unity game engine). The reason for this is be to differentiate between Boolean attributes (such as isValid) and methods that return Booleans (such as IsValid(data)). As a second choice, I would use camel case for methods.
underscore prefix for non-public properties
possibly (not sure yet) the s and t prefixes from C# for the relevant things. As the Zen of Python says "Namespaces are one honking great idea -- let's do more of those!" (I consider prefixes to have a similar effect)

Interfaces

Names for interfaces are similar to class names. They use pascal case and are usually nouns. Sometimes they can be named with an adjective, for example "Readable".

In the book Clean Code, Uncle Bob recommends avoiding the I prefix for interfaces. The Java naming conventions recommend the same. For example interface Foo.

The C# coding conventions recommend prefixing interfaces with I. For example interface IFoo.

Personally, I have a minor preference for avoiding the prefix. That's because, as a user of the code, I'm not particularly interested on whether I'm working with an interface or a class.

Enums

The Java convention is to treat enums like classes with constants. This means to name the enum type with pascal case and the fields fully uppercase.

C# also treats them the same as classes. This means to name both the enum type and the fields using pascal case.

Personally, I prefer the Java convention because it differentiates between constants and other values.

Events, event handlers, messaging systems and commands

There are a few things to consider regarding events and their relevant functions.

Event names

Event names:

refer to an action
are normally named using verbs. For example "downloaded", "loaded", "deleted", "damaged", "moved".
generally use present tense for events that fire before an action starts. For example, before submitting a password reset request, you might fire an event named "passwordResetRequestSubmitting".
generally use past tense for events that fire after an action completes. For example, after submitting a password reset request, you might fire an event named "passwordResetRequestSubmitted".

In my experience, these conventions are common across many languages. However, there isn't much official documentation for them. One exception is with .NET, where they formally state these guidelines.

For the actual name of the event, you can use whatever makes sense to you. If your event is created in a class, the class name may provide sufficient context. For example, if you have a class Shape, you may have an event named areaChanged. The usage would be something like myShape.areaChanged += someHandler or myShape.areaChanged.subscribe(someHandler). The event name "areaChanged" is sufficiently descriptive in this case.

In terms of casing, follow the convention in your programming language. C# uses pascal casing for public members (including events). Most other languages use camel casing.

Some example event names are:

fileDownloading / fileDownloaded
userRegistering / userRegistered
uiElementXUpdating / uiElementXUpdated

Event handlers

For event handler functions, there are a few conventions. In front end, React tends to use the prefix "handle". C# recommends the suffix "EventHandler". Other languages may have other conventions.

Some example names of event handler functions are:

handleUserSubscribed / userSubscribedHandler / UserSubscribedEventHandler
handleFileDownloaded / fileDownloadedHandler / FileDownloadedEventHandler

My personal preference is to use the "handle" prefix. This keeps the function a verb, which is the convention for functions.

"On" functions

Functions that exist solely to raise events tend to have the name on<EventName>. For example "onAreaChanged".

One case for using these is in classes that may be derived.

Here's a C# example:

class Foo
{
  public event EventHandler FileDownloaded;

  protected virtual void OnFileDownloaded(EventArgs e)
  {
    EventHandler handler = FileDownloaded;
    if (handler != null) {
      FileDownloaded(this, e);
    }
  }

  public void Something()
  {
    OnFileDownloaded(EventArgs.Empty);
  }
}

Here, we have a method named OnFileDownloaded whose only purpose is to raise the event.

This convention may work a bit differently in front end, but it still follows the general idea. For example, in React, you can name props something like "onClick" or "onSomeEvent". Event handler functions that you define inside a component can use the "handle" prefix.

Here's a React example:

import React from 'react';

const ParentComponent = () => {
  function handleButtonClicked() {/* do something */}
  return <ChildComponent onClick={handleButtonClicked} />;
};

const ChildComponent = ({ onClick }) => {
  const handleClick = (e) => {
    console.log("clicked");
    onClick("foo");
  };
  return <button onClick={handleClick}>Click me</button>;
};

Here, each component creates event handler functions prefixed with "handle". The child component has the prop named "onClick". In the child component, the handleClick function calls the onClick prop.

More global message names

PubSub (message bus) and analytics have similarities to local events, but they are more global. They span a much larger area of the codebase. The can even span multiple applications (as might be the case for analytics).

With these, it's important to use more specific names, otherwise you won't know what they refer to.

A good way to do this is to use namespaces and prefixes, along with specified delimiters.

For example, with PubSub event names, you can have a namespace for the relevant area of the codebase. The format of the event name can be <areaOfCodebase>/<eventName>. For example:

ui/themeChanged
ui/fontSizeChanged
player/damaged
player/poweredUp
user/registering
user/registered
user/deleted

And, as explained on clean analytics by David Wells, for analytics you could use a format like <Source>:<object>_<actionName>. For example:

site:newsletter_subscribed
app:site_deployed
cli:user_login
api:site_created

These are just examples. In your own codebase, you can use as many namespaces as you want. The namespaces can be anything.

Likewise, the delimiter(s) can be anything you want. Some examples are "/", "::", ":", "_", or even no delimiter.

Commands

Commands are written similarly to functions. They are verbs in an imperative mood. They are also used in PubSub. The notes about namespaces and delimiters, mentioned above, apply to them.

Commands also usually expect a response. In other words, a command such as "CreateUser" will have a response message such as "CreateUserResult", "CreateUserSucceeded" or even "UserCreatedNotification". Overall, I'm not aware of strong conventions for these, so you can probably use whatever you like.

My personal preference for response names comes from Jimmy Bogard's post on message naming conventions. I generally append "Result", "Reply" or "Response" to the original command name.

Some example formats for command names and their namespaces are <Verb><Subject> and <subject>/<verb>. For example:

Possible commands are "RegisterUser" or "user/register". Possible responses are "registerUserResponse" or "user/register_result"
Possible commands are "DamagePlayer", "player/damage". Possible responses are "DamagePlayerResponse", "player/damage_result"

File names

For file names, you need to consider conventions for casing, as well as what to name the file based on the code it contains.

File name casing conventions and delimiters

For file naming, there are different conventions depending on the language, framework and style guide you follow.

Many conventions recommend file names that are all lower case. Words can be separated with either hyphens (-) or underscores (_). For example:

in HTML, the convention is all lower case, with hyphens as separators. Underscores are far less common. One reason for this is because the HTML file name may reflect in the URL (especially with older servers). Underscores in URLs are far less common than hyphens.
in CSS, the convention is all lower case with hyphens or underscores as separators
In Python, PEP 8 recommends file names to be all lower case, with underscores as separators
the Google JavaScript style guide recommends file names to be all lower case, with underscores or hyphens as separators

Between hyphens and underscores, you can use either. Both are acceptable. In general, I prefer to use hyphens to be consistent with my CSS classes (which conventionally use hyphens) and for the reasons mentioned for the HTML. However, if you commonly use snake case in your programming language, or if you don't write HTML and CSS, it might feel more consistent to use underscores instead of hyphens.

Some example file names are:

index.html, index.css, index.js
third-party-analytics.js
enemy-mover.js

Along with that, there are other conventions that recommend camel or pascal case for your files. For example:

C# and Java recommend naming your file the same as the main thing in your file. This means using pascal case, same as your classes and interfaces.
the AirBnB JavaScript style guide recommends naming your file the same thing as your default export. Again, this means using camel or pascal case, at least for your JavaScript files.
React takes it a step further and recommends naming all of your files consistently in each folder. For example:
- MyComponent.js
- MyComponent.css
- MyComponent.test.js (test files tend to have the special extension .test.js)

So which should you choose? First, consider if one of the conventions is more common than the others for your programming language or framework. That's the natural choice. Otherwise, you can do whatever you like. My personal recommendation is to choose the naming convention that best matches the code in your files. For example, when working on the front end, the convention is for everything in your HTML and CSS to be lower case with hyphens as separators. Therefore, you might want to use that as the naming convention.

As another example, when working on React applications that use CSS modules, you might prefer to write CSS using pascal case and underscores. This makes it easier to use your CSS in your JavaScript, for example styles.Foo_bar (where Foo_bar is your CSS class), as hyphens aren't allowed in JavaScript. In this case, it may feel more natural to name your files using pascal case.

Choosing a file name based on the code it contains

In general, you want to name your file based on its purpose.

This is supported by the C# naming conventions and Java naming conventions. They state that your file name should be the same as the main thing you define in your file. For example, if you define a class Foo, your file name should be Foo.cs or Foo.java.

The AirBnB JavaScript style guide also agrees with this. It states that your file should be named after your default export. Whether or not you use default exports is a separate matter. But the point is the same. It means to name it after the purpose, or the most important thing in your file. Normally (but not always) that's thing that you would export default, if you were using export default.

One exception is if your default export is named "main", "setup" or something similar. It doesn't make sense for a file to be called "main", especially if many files have a similar default export. In that case, consider what the purpose of the file is. An alternative is to consider what the equivalent OOP code would be.

For example, consider that you have a class that deals with carousel functionality. Your OOP code would probably be a class named "Carousel". In comparison, if you write it using functions, it might look like this:

function handleChangeToNextSlide() {
  // code to change to next slide when user clicks the relevant button
}

function main() {
  // find DOM elements that are supposed to be carousels
  // set up event listeners on those elements
}

export default main;

In the equivalent OOP code, the code in main would be in the constructor of the class Carousel. In this case, my recommendation would be to name the file carousel. That's its true purpose. Alternatively, you could also change main to setupCarousel or something and name the file after that.

As for some other cases:

If your file defines multiple classes: Well, most style guides would tell you to avoid files with multiple classes. Consider whether you can separate each class into its own file. Although, if you only have one public class, then that's fine. Name the file after the one public class, not the private ones.
If you use functions instead of classes, there might be some cases where none of the functions would suitable to export default. Again, you need to consider what the purpose of the file is. For example, if you have some functions that are used in your test files, then perhaps "test-utilities" would be a good name. Alternatively, you can consider what the equivalent OOP code would be. You would probably have a static class with static methods. Name your file after the name of that static class.

Package names and namespaces

In practice, many packages don't follow naming conventions at all. That's because a developer can upload a package with whatever name they want. There usually aren't many checks.

However, there are naming conventions for packages and for different package repositories.

Java and Maven use the format of <groupID><artifactID>. The group ID part is generally a reversed domain name. For example, if your domain is example.com, the group ID would be "com.example". It can have subgroups (additional namespaces). For example "com.example.plugins". The artifactID is the name of the jar. For example "junit" or "spring-web". In general, artifact IDs tend to be fully lower case with hyphens to separate words.

NPM (node package manager) tends to use direct package names, such as "react-dom", or prefixed with a namespace or company name, such as "@babel/preset-env". They tend to be fully lower case with hyphens to separate words.

With NuGet (package repository for .NET), the number of namespaces vary, just like with Maven and subgroups. There are many packages with a single name, such as "Moq". There are also many packages of the format <CompanyName>.<Package>, such as "AWSSDK.Core". There are also packages with many namespaces, such as "Microsoft.Extensions.FileProviders.Abstractions". If you want to follow the example of the packages released by Microsoft, then use pascal case, optionally a company prefix and as many namespaces as you need.

Namespaces (in code) seem to follow similar concepts and conventions to packages.

Final tips

Remember that naming is hard.

There are only two hard things in Computer Science: cache invalidation and naming things. - Phil Karlton

However, spending some time to come up with a reasonable name is usually worth it.

Also, as always, be pragmatic. It's okay to break these conventions once in a while. They are only here to help you make good and consistent decisions most of the time. For example, it's okay if you feel that adding the data structure to the name will help, such as userList. It's up to you to decide what's best for your project.

In addition, you probably can't spend an unreasonable amount of time coming up with good names. So, sometimes, if you've already spent too long, you might need to use the best name you've come up with so far and move on.

Overall, the most important thing from this article is that you understand the principles behind naming. In particular, that names should make the code easy to understand. If you understand that, then you'll be fine. You'll be able to come up with your own solutions and conventions even in unfamiliar situations.

Final notes

So that's it for the article. I hope that you found it useful.

If you've encountered any awful names in code you've worked on, please leave a comment with them!

Also, if you want to discuss anything, disagree with anything, or have any feedback in general, please leave a comment below.

Alright, see you next time :)

Image credits

Cover photo (modified) - Photo by Paul Stollery on Unsplash
Clear Bulb Beside White Notepad on White Surface - Photo by Burak Kebapci on Pexels
Green leaf with white card - Photo by Helena Hertz on Unsplash

Carousel slider tutorial with HTML, CSS and JavaScript

Spyros Argalias — Tue, 01 Jun 2021 12:01:10 +0000

In this post we'll look at how to make a simple carousel with HTML, CSS and JavaScript. We will use good code practices, keep accessibility in mind and also consider how we can test the carousel.

The carousel will be a "moving carousel". Slides will move in from left to right, or right to left, with a transition. It won't be an in-place carousel where a slide fades out while another one fades-in.

If you prefer a video version, here it is. It goes into much more detail than this post.

Basic functionality

We'll start with the basic functionality. That's the basic HTML, CSS and JavaScript.

HTML

We'll keep the HTML fairly simple. We basically need:

a container for the carousel
the carousel controls
the slides

We won't focus very much on the HTML head or anything other than the carousel. The rest is standard stuff.

As for the actual carousel, here is some HTML we can use.

<head>
<!-- Import font-awesome somewhere in the HTML -->
  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.3/css/all.min.css" integrity="sha512-iBBXm8fW90+nuLcSKlbmrPcLa0OT92xO1BIsZ+ywDWZCvqsWgccV3gFoRBv0z+8dLJgyAHIhR35VZc2oM/gI1w==" crossorigin="anonymous" referrerpolicy="no-referrer" />
  <link rel="stylesheet" href="./index.css">
</head>

<body>
  <div class="carousel" data-carousel>
    <div class="carousel-buttons">
      <button
        class="carousel-button carousel-button_previous"
        data-carousel-button-previous
      >
        <span class="fas fa-chevron-circle-left"></span>
      </button>
      <button
        class="carousel-button carousel-button_next"
        data-carousel-button-next
      >
        <span class="fas fa-chevron-circle-right"></span>
      </button>
    </div>
    <div class="slides" data-carousel-slides-container>
      <div class="slide">
        <!-- Anything can be here. Each slide can have any content -->
        <h2>Slide 1 heading</h2>
        <p>Slide 1 content
      </div>
      <div class="slide">
        <!-- Anything can be here. Each slide can have any content -->
        <h2>Slide 2 heading</h2>
        <p>Slide 2 content
      </div>
    </div>
  </div>
</body>

In the head, we are linking font awesome and also our custom styles CSS file.

In the body:

we have an outer div for the entire carousel.
we have two buttons, one for "previous slide" and one for "next slide". The buttons use font-awesome icons.
we have a div for the slides. Inside that, we have a div for each slide. The content inside each slide is irrelevant to us, it can be anything.

As for the data- attributes, those are what we'll use as selectors in JavaScript.

I personally prefer using data- attributes for JavaScript because I want to separate concerns. For example, classes are standard to use for CSS. When someone tries to change the styling of the carousel in the future, they may replace the class name for a more descriptive one. They may also change some CSS modifier classes or something. I don't want them to be paranoid that if they change the CSS they may break the JavaScript, or the automated tests, or the asynchronous content insertions, or anything else. I want them to feel safe when working with the CSS.

This means, that I do not use classes to select elements with JavaScript.

An exception to this is if you use classes with a prefix such as js-. E.g. <div class="js-carousel"></div>, which are exclusively for JavaScript use. That achieves the same result.

But my preference is to use data- attributes. That's what data-carousel and the others are for.

CSS

Our CSS:

is going to have the basic styling for our carousel
is going to have the mechanism for changing the slides

The way our carousel will work is by having all slides horizontally next to each other. However, only one slide will show at a time. That's because every slide, except the one that's visible, will be overflowing outside of the top-level carousel div. That div will have overflow: hidden, so nothing that's overflowing will show.

We'll decide which slide is currently showing with the line transform: translateX(/* something */). That way, we'll translate the slides div, so that only the correct slide is visible.

Here is the CSS.

.carousel {
  --current-slide: 0;
  /* we set position relative so absolute position works properly for the buttons */
  position: relative;
  overflow: hidden;
}

.carousel-button {
  /* vertically centering the buttons */
  position: absolute;
  top: 50%;
  transform: translateY(-50%);
  z-index: 1;

  /* basic styling */
  padding: 0;
  margin: 0.5rem;
  border-radius: 50%;
  background-color: transparent;
  border: none;

  font-size: 1.5rem;
  cursor: pointer;

  transition: color 0.1s;
}

.carousel-button:hover {
  color: rgba(0, 0, 0, 0.5);
}

.carousel-button_next {
  /* The "next slide button" will be at the right */
  right: 0;
}

.slides {
  display: flex;
  transition: transform 0.5s;
  transform: translateX(calc(-100% * var(--current-slide)));
}

.slide {
  flex: 0 0 100%;
}

@media screen and (min-width: 768px) {
  .carousel-button {
    font-size: 2rem;
    margin: 1rem;
  }
}

With this CSS, every div has its default width of 100%. This means that the carousel will take the full width of its parent container. Every slide will also take up the full width of the carousel.

Controls

In the carousel-button class, we provide some simple styling for the buttons. We're using font-awesome icons, so we give them a font-size so they're large and visible. We also remove some of the default button styling (things like borders and background color).

Also, we position the buttons in the middle (vertically) of the entire carousel. We do this by using the position: absolute; top: 50%; transform: translateY(-50%); trick.

Changing slides

The trick for how the carousel actually changes slides is the CSS in .slides and .slide. In .slide, we make each slide have 100% of the width of the carousel. This is done with the flex property. In other words, one slide will take up the entire width of the carousel.

Since .slides is display: flex;, all of the slides will be horizontally next to each other. This means that one slide will take up the entire width of the carousel and all other slides will overflow horizontally next to it. The carousel div has overflow: hidden;, so none of the overflowing slides will show.

At some point, using JavaScript, we'll move the .slides div to the right or left. This means that the slides will move, so a different slide will be visible inside the carousel.

The declaration transform: translateX(calc(-100% * var(--current-slide))); is our movement mechanism. Here we're saying to move the slides container -100% (the full-width of the carousel, or the full width of a slide) to the left (the negative sign means to the left), as many times as the slide index we're on.

For example, if we're on slide index 0 (first slide), -100% * 0 = 0, so we don't translate at all and the first slide is visible.

If we're on slide 1, then -100% * 1 = -100%, so we translate 100% (one slide width) to the left. This means that we're displaying slide index 1 (the second slide).

We'll set the --current-slide property using JavaScript.

JavaScript

Our JavaScript needs to:

handle events for the two buttons (switch to previous slide and next slide)
work independently for any number of different carousels on the page

Here is the JavaScript.

function modulo(number, mod) {
  let result = number % mod;
  if (result < 0) {
    result += mod;
  }
  return result;
}

function setUpCarousel(carousel) {
  function handleNext() {
    currentSlide = modulo(currentSlide + 1, numSlides);
    changeSlide(currentSlide);
  }

  function handlePrevious() {
    currentSlide = modulo(currentSlide - 1, numSlides);
    changeSlide(currentSlide);
  }

  function changeSlide(slideNumber) {
    carousel.style.setProperty('--current-slide', slideNumber);
  }

  // get elements
  const buttonPrevious = carousel.querySelector('[data-carousel-button-previous]');
  const buttonNext = carousel.querySelector('[data-carousel-button-next]');
  const slidesContainer = carousel.querySelector('[data-carousel-slides-container]');

  // carousel state we need to remember
  let currentSlide = 0;
  const numSlides = slidesContainer.children.length;

  // set up events
  buttonPrevious.addEventListener('click', handlePrevious);
  buttonNext.addEventListener('click', handleNext);
}

const carousels = document.querySelectorAll('[data-carousel]');
carousels.forEach(setUpCarousel);

This code may be appear a bit confusing because of the nested functions. If you're not used to this syntax, then here is a class alternative for the setUpCarousel function which does exactly the same thing.

class Carousel {
  constructor(carousel) {
    // find elements
    this.carousel = carousel;
    this.buttonPrevious = carousel.querySelector('[data-carousel-button-previous]');
    this.buttonNext = carousel.querySelector('[data-carousel-button-next]');
    this.slidesContainer = carousel.querySelector('[data-carousel-slides-container]');

    // state
    this.currentSlide = 0;
    this.numSlides = this.slidesContainer.children.length;

    // add events
    this.buttonPrevious.addEventListener('click', this.handlePrevious.bind(this));
    this.buttonNext.addEventListener('click', this.handleNext.bind(this));
  }

  handleNext() {
    this.currentSlide = modulo(this.currentSlide + 1, this.numSlides);
    this.carousel.style.setProperty('--current-slide', this.currentSlide);
  }

  handlePrevious() {
    this.currentSlide = modulo(this.currentSlide - 1, this.numSlides);
    this.carousel.style.setProperty('--current-slide', this.currentSlide);
  }
}

const carousels = document.querySelectorAll('[data-carousel]');
carousels.forEach(carousel => new Carousel(carousel));

Basically, we're holding some state, the currentSlide and the numSlides variables. We're also holding references to some HTML elements, such as the carousel element, because we'll need them when changing slides. Finally, we add event listeners to the buttons.

When the user clicks on the "next slide" button, we run the handleNext function. The call to modulo(currentSlide, numSlides) sets currentSlide to the correct index for the next slide. So, if there are 5 slides, and we're on slide index 0, it will set currentSlide to 1. But, if we're already on slide index 4 (the fifth and final slide), then the next slide index is 0, not 5. The modulo function takes care of the wrapping back to 0 for us.

Really, we could have used the % (modulo) operator for this. The reason why we have the modulo function is because % doesn't play well with negative numbers. -1 % 5 evaluates to -1, rather than 4 (the index of the slide we would actually want). We created our own modulo function to handle that case.

Finally, we set the CSS property --current-slide to the correct number. Then, the CSS changes the visible slide by translating the slides div appropriately.

The independence of different carousels on the page happens because we use querySelector on the parent carousel element, not on the document. This means that, for example, carouselElement1.querySelector([data-carousel-button-next]), will only get the button inside that carousel element. Whereas document.querySelector('[data-carousel-button-next]') would get the first matching element it finds on the page, rather than the target carousel.

Accessibility

At the moment, this carousel is very unfriendly to screen reader users. You'll need to actually use a screen reader and listen to it to hear it for yourself (or watch the accessibility section of the embedded video), but basically:

it doesn't mention anything about the content being a carousel
for the buttons, it just says "button" and nothing else (because the buttons don't have text or a label)
on "auto read", it reads through all of the content of every slide, as though it was a normal web page full of text (because we're not telling it to only read the visible slide)

To fix those issues, we need to go to the WAI-ARIA authoring practices document. There is a section for carousels. We just go to it and follow the instructions. It's actually not too difficult. It has step-by-step instructions for us.

In the end, our HTML looks like this:

<div
  class="carousel"
  aria-role="group"
  aria-roledescription="carousel"
  aria-label="Student testimonials"
  data-carousel
>
  <div class="carousel-buttons">
    <button
      class="carousel-button carousel-button_previous"
      aria-label="Previous slide"
      data-carousel-button-previous
    >
      <span class="fas fa-chevron-circle-left"></span>
    </button>
    <button
      class="carousel-button carousel-button_next"
      aria-label="Next slide"
      data-carousel-button-next
    >
      <span class="fas fa-chevron-circle-right"></span>
    </button>
  </div>
  <div
    class="slides"
    aria-live="polite"
    data-carousel-slides-container
  >
    <div
      class="slide"
      aria-role="group"
      aria-roledescription="slide"
      aria-hidden="false"
      aria-labelledby="bob"
    >
      <h2 id="bob">Bob</h2>
    </div>

    <div
      class="slide"
      aria-role="group"
      aria-roledescription="slide"
      aria-hidden="true"
      aria-labelledby="alice"
    >
      <h2 id="alice">Alice</h2>
    </div>
  </div>
</div>

A quick summary of what we did is:

we added an aria-role, aria-roledescription and aria-label to the carousel div. Now, the screen reader says something like "Student testimonials carousel", immediately indicating that this is a carousel and what content it represents.
for each button, we added an aria-label. Now the screen reader says something like "button previous slide", instead of just "button". (An alternative technique here would be to add "screen-reader only text". This is text that exists in the HTML but is hidden visually using particular methods.)
we added an aria-role and aria-roledescription to each slide. Now the screen reader knows when it's entering a slide or leaving a slide and it will notify the user as necessary.
we also added a label to each slide using aria-labelledby. This is the same as aria-label except that you point it to some text that already exists on the page, using an HTML ID. In this case, since our label already exists on the page (the heading for each slide), we used aria-labelledby instead of aria-label.
we added aria-hidden="true" to the hidden slides. Now the screen reader won't read them.
we added an aria-live region. Now the screen reader will re-read the content of the carousel whenever there are changes (when the user changes the slide).

There are some other aria attributes that would be useful, but I'm ignoring them for now because they're not mentioned in the carousel part of the WAI-ARIA authoring practices. One example is aria-controls. If you want to learn more about these, it might be worth looking at the WAI-ARIA authoring practices in your own time. If you want to learn more about accessibility in general, I've written a learning guide in Web accessibility - Everything you need to know.

Our JavaScript needs some updates as well. Specifically, when we change slides, we need to change the aria-hidden property to false for the new active slide. We also need to hide the previous slide that we're no longer looking at.

Here is some example code we can use:

function changeSlide(slideNumber) {
  // change current slide visually
  carousel.style.setProperty('--current-slide', slideNumber);

  // handle screen reader accessibility
  // here we're getting the elements for the previous slide, current slide and next slide
  const previousSlideNumber = modulo(slideNumber - 1, numSlides);
  const nextSlideNumber = modulo(slideNumber + 1, numSlides);
  const previousSlide = slidesContainer.children[previousSlideNumber];
  const currentSlideElement = slidesContainer.children[slideNumber];
  const nextSlide = slidesContainer.children[nextSlideNumber];

  // here, we're hiding the previous and next slides and unhiding the current slide
  previousSlide.setAttribute('aria-hidden', true);
  nextSlide.setAttribute('aria-hidden', true);
  currentSlideElement.setAttribute('aria-hidden', false);
}

Testing

What ways are there to test something like this?

In short, I would write end-to-end tests for it. I would hesitate to write unit tests for it.

Here's why.

An end-to-end test shows you that the entire thing works correctly.

Depending on your test framework, you could do things like:

check that only a particular div (slide) is visible on the page, and the others aren't
check that the correct div (slide) is visible after pressing the next / previous slide button
check that the transition for changing slides works correctly

But if you unit test, you can only check that your JavaScript works correctly.

You could do a test where you set up some HTML, then run your JavaScript and finally check that the resulting HTML is what you expect.

Or you could do something like spy on your JavaScript code, run your JavaScript and ensure your spies were called.

With the first unit test example (where you check the final HTML), the problem is that, while your tests may be passing, your carousel may not be working. For example, someone may have changed how the CSS works. They may have renamed the property --current-slide to --index or whatever else. Maybe they changed the entire CSS mechanism for changing the slides (for example, to improve performance).

In this case, your JavaScript will be executing without errors and the tests will be passing, but the carousel won't be working.

The tests won't provide confidence that your code works.

The only thing they'll do is freeze your JavaScript implementation. This is the scenario where you've already checked the carousel yourself, manually, in the browser. You think "I can see that it's working, let me write some unit tests for it that check that the JavaScript is doing X". What this does, is it prevents anyone from accidentally changing the JavaScript in the future. If they do so, the tests will fail.

But, it also makes intentional changes more difficult. Now, if you want to change the implementation in the future, you need to change your CSS, JavaScript and your 10 tests. This is one of the reasons why people dislike unit tests. They make changes to the implementation more difficult (at least with unit tests like these).

So, for these reasons, I would personally recommend writing end-to-end tests instead. Now, if you really want to prevent accidental changes in the JavaScript, that's fine. You need to do what you need to do. It's up to you to decide if the peace of mind is worth the downsides and the time it takes to write those tests.

As for the other scenario of unit testing, where you check that your spies were called, I just don't see a benefit to that. With those tests, you're not even testing that your JavaScript is doing what you think. You could break the JavaScript implementation in the future and your tests would still pass, as long as you're calling the same functions.

But, those are just my thoughts on the matter. I'm open to differences in opinion. Please leave a comment below if you think I'm missing something.

Final notes

So that's it. I hope that you found this article useful.

If you want a fuller view of the code, here is the code repository.

Please note that this is not meant to be production-ready. The code can be cleaned up more. It can probably be made more appropriate to what you need to use. Etc.

This is just a little tutorial to show you the general idea on how to make a simple carousel.

If you have any feedback, anything that was missed or could have been done better, or anything else, please leave a comment below.

Alright, thanks very much and see you next time.

Clean code & programming principles – The ultimate beginner’s guide

Spyros Argalias — Fri, 14 May 2021 11:18:14 +0000

This article is the beginner's introductory guide to programming principles.

First we're going to examine what good code is. The qualities of good code. That's because those qualities come before programming principles. Programming principles are just guidelines to help us apply those qualities to code.

Afterwards, we'll examine the most important programming principles, one-by-one, at an introductory level.

Hopefully, this article will feel less like "have small functions" and more like "these are the qualities you want in code, for reasons 1, 2 and 3. So as you can see, small functions help you achieve those in ways X, Y and Z".

I believe that this kind of understanding is more beneficial than just knowing some arbitrary rules. They're especially helpful if you've been stuck on how to apply certain programming principles in the past. Knowing how they help and what they're trying to achieve should help you apply them even in unfamiliar situations.

Target audience

I believe that this article is suitable for all audiences.

If you're a beginner developer, some of the things mentioned in this article may be too abstract. But, some others should be useful immediately. Nevertheless, this article will give you an understanding that will help you very much in the future, even if you don't understand all of it now.

If you're an intermediate-level developer, you'll probably gain the most benefit. You are probably writing medium to large programs. You've got the hang of the basics. Now, you need to learn how to write code that scales (in size). This is what programming principles help you with.

If you're an advanced-level developer, you'll probably know most of these things already. However, you might enjoy this article nonetheless.

Qualities of good code

What is good code?

To answer that question, first we need to examine the requirements of code. Then, the qualities that we (people) need for something to be easy to work with. After that, the qualities of good code become obvious.

If you want to skip the discussion, here are the conclusions:

The requirements of code are that:

it should work as intended, without bugs
it should be built as quickly and efficiently as possible (without sacrificing quality) (just like all products)
it should be easy and fast to work with and modify (for the next time you need to work with it)

Some of our limitations are that:

we can't remember too much at any one time. This means that we won't remember that modifying X will break Y and Z.
we find complicated things disproportionally more difficult than simple things
making multiple similar changes is very error-prone for us
we have bad days where we are bored, can't focus and don't pay too much attention
we always make mistakes, no matter what. This means that we need tests (manual or automated) and other error-catching things.

From those two, after a bit of reasoning, we conclude that code should:

be simple (because we're bad with complicated things)
be immediately understandable (so we can understand it quickly and make changes faster. Also so we don't misunderstand it and create bugs, especially if we're not really focusing that day)
be organised (so we can understand the project structure easier and find the files we need to modify faster)
be independent (so we can make reasonable changes to X without breaking 1,000 other things in the project)
have minimal duplication (because we're bad with repetitive changes. They're also slower)

More details and explanations are below. If you're not interested, please skip to the next section.

Requirements of code

Software is a product. Businesses hire programmers to build software products. It's not abstract art (usually). It's something built for a specific purpose.

From a business perspective, products:

have to be fit for purpose and work as intended
should be as cheap and efficient as possible to create (without sacrificing quality)

The same applies to software.

But software has some unique aspects. It needs constant modification. That's because software is often never "finished". Companies may be requesting new features for decades after initial release. Also, there may be bugs that need fixing at any time. Finally, during development, programmers constantly modify the code.

Therefore, for the software product to be as efficient and cheap as possible to create and maintain, the code needs to be easy and fast to work with and modify.

Not to mention that being easy to work with means less bugs due to changes.

So, the requirements of code are that:

it should work as intended, without bugs
it should be built as quickly and efficiently as possible (without sacrificing quality)
it should be easy and fast to work with and modify (for the next time you need to work with it)

For even more detail on this, please see the post requirements of software.

Human limitations and bad code

Code can be difficult to work with because of our limitations.

Here are some of our limitations and what we can do to counter them.

Memory

We can't remember too much at any one time. The quote about short term memory and the magical number 7 plus or minus 2 comes to mind.

To counter that, we need code to be sufficiently independent (decoupled) and without hidden dependencies. That way, when we're modifying code, we won't accidentally break it due to forgetting to also update a dependency that we didn't remember existed.

We like things simple

Complicated things are disproportionally more difficult for us. This is partly because we need to keep in mind many things about them at once. Therefore, we should make code simple and easy to work with.

We are impatient

We get impatient, skim things often, have bad days and get bored.

To counter that, we should make code simple, easy to understand and easy to work with.

We are bad with repetitive work

Repetition is error-prone for us, particularly if every repetition is slightly different.

Repetitive work means more chances to make an error. Also, probably due to impatience and lack of focus, we're more likely to rush this type of work. We don't usually provide the necessary care and attention to every single change. To help, we should minimise repetitive work.

We make mistakes

We make mistakes often and in all areas of life. This includes programming, mathematics, engineering, art, design and everything else.

Therefore, we always need to double check our work. As a result, we use practices like code reviews and automated testing. We also use tools to statically analyse our code.

How we should work on software

We should work on software deliberately. We should know and understand as much as possible about the code we're currently working on. This means that we'll be as certain as possible that we're doing the right thing and that we won't break anything.

In comparison, if we're just trying things at random, we're not certain that they'll work. Most of the things we try won't work, except the last one (at which point we'll stop). Also, we'll only know whether they work or not because of our tests. We'll probably manually test everything we try.

This is problematic, because, since we're not really sure what we're doing, we might have broken other things that we won't think to test.

So, to minimize the chance of error, it's important to understand as much as possible about what we're doing.

The best way to do that is to make code simple, easy to understand and easy to work with.

How code should be

Everything we've examined so far points to a certain way for how code should be. Code should:

be simple (because we're bad with complicated things)
be immediately understandable (so we can understand it quickly and make changes faster. Also so we don't misunderstand it and create bugs, especially if we're not really focusing that day)
be organised (so we can understand the project structure easier and find the files we need to modify faster)
be independent (so we can make reasonable changes to X without breaking 1,000 other things in the project)
have minimal duplication (because we're bad with repetitive changes. They're also slower)

Next, let's examine the programming principles.

Be pragmatic - The most important principle

Not just in programming, but pretty much everything in life, being pragmatic is essential.

It means to remember the true goal of what you're trying to accomplish, maximise that, and not get side-tracked.

In programming, your aims are to:

have code that works correctly
make your changes as quickly and efficiently as possible
make the code easy and fast to work with for the next time someone works on it

The programming principles are guidelines to help you do that. But, your aims come first. If a programming principle will be detrimental to your aims, you shouldn't apply it.

Don't apply principles to the extreme

For example, having code that's short is commonly considered a good thing. It has many benefits which we'll examine later. But you should never make your code shorter if it will make it more difficult to understand and work with.

Don't play "code golf", where you use complicated syntax and mathematical tricks to make the code as short as possible. That makes the code more complicated and more difficult to understand.

In other words, have code that's short (the guideline), but only if it makes the code simpler and easier to understand (your aims).

Balance time spent refactoring

Additionally, you need to make your changes in a reasonable timeframe. You've got to balance how much time you spend refactoring code against how much benefit it will provide.

For example, if you have some code that's very difficult to understand, you absolutely should refactor it. It might take a few hours, but it's probably worth it. It will make your project easier to work with in the long-term. You'll reclaim the time you spent refactoring through higher efficiency in the future.

But, if you have some code that's almost perfect, don't spend 3 days refactoring it only to make it slightly better. You would have spent 3 days for almost no benefit. Instead, you could have used that time in better ways. You could have written a new feature, or refactored a more suitable part of the codebase.

The point here is: You need to prioritise based on value. That usually means keeping code pretty clean and refactoring when needed. But it probably doesn't mean spending an unreasonable amount of time refactoring for almost no benefit.

YAGNI

Another important thing to talk about is YAGNI. It stands for "you ain't gonna need it".

It warns you against coding things in anticipation of features you might need in the future. For a simple contrived example, you may create a function foo, which has the parameter bar. But you might think "feature X might be added in the future, which will need a parameter baz, so let me add it to the function now".

In general, you want to be wary of doing that. Firstly, that feature is probably never going to be needed. Secondly, you increase the complexity of the code today, making it harder to work with. Thirdly, if that feature is needed in the future, you might code it differently to how you anticipate today.

Instead, code the simplest solution for what you need today. Then, make the changes needed for that feature when it's needed (if ever).

This is optimal, because you won't needlessly waste your time or make the codebase more complicated. Even if you did predict a feature correctly, it will be much faster to code it when you need it compared to all of the time you would have spent coding everything prematurely.

Personal recommendations

Create a fairly simple solution for what you need today, that is simple to understand and work with.

Write clean code and maintain your code so it's fairly clean. Refactoring may take time upfront, but it pays off in the long-term because the code is easier to work with.

Only apply programming principles if they'll make your code better and easier to work with.

If you're newer to programming principles, consider applying them more heavily than necessary when you practice. You'll get practice applying them and you'll get a feel for when you've taken them too far.

KISS (keep it simple stupid) and the principle of least astonishment

KISS (keep it simple stupid) is another principle that's universal to most things in life. It means that your code should be simple and easy to understand.

The principle of least astonishment is also important. It means that things should work exactly as you expect them to, they shouldn't be surprising. It's a cousin to KISS.

If you don't keep things simple and easy to understand, then:

everything takes longer to understand
sometimes you might not understand how things work, even after spending a lot of time on them
you might misunderstand how things work. Then, if you modify the software, you could easily create bugs.

How to apply KISS and the principle of least astonishment

Here are some guidelines for making your code simple and easy to understand.

Default to writing dumb code, avoid writing clever code

Dumb code is simple code. Clever code is probably not simple code.

Really clever code is not simple, it's difficult to understand and it's tricky. People will misunderstand it and create bugs as a result.

Keep code short and concise

Shorter code is more likely to be simple.

Short code means that units, such as functions and classes, do less things. That means they're simpler and easier to understand.

Use good names

If you have a well-named function, you can understand what it does from the name, without reading the function body. The same applies to all code. This makes your work faster and easier.

The name also provides meaning, which helps you decipher code faster.

For example, if you see the code 2 * Math.PI * radius, you may not understand what it's doing and why, even after reading it. You may look at it and be like "what? PI, radius?? What is this???".

But, if you see const circleArea = 2 * Math.PI * radius, straight away you're like "oh I get it. It's calculating the area of the circle, of courseeeee. No wonder PI and radius are there...".

Always consider the programmer reading the code for the first time

This is the person you're trying to optimise the code for. The colleague who has never worked on this code before, or even yourself, 6 months from now, when you've forgotten what this code does and how it works.

"Any code of your own that you haven't looked at for six or more months might as well have been written by someone else." - Eagleson's law

Consider that when you're writing the code, you know what the code needs to do and you just code it. But the person reading the code for the first time, has to parse what the code is doing and also has to understand why it's doing it.

Consider immutability (never reassigning the values of variables)

Immutability provides a guarantee that a value will never change.

This makes the code simpler to understand, because you don't have to trace through the code for the history of the variable, just in case it happened to change anywhere in your codebase.

Follow existing conventions

Code that follows existing conventions is unsurprising. Code that breaks conventions can be very unexpected. Someone who skims the code may not realise that it doesn't follow the convention, so they may misunderstand how it works.

Try to follow conventions which already exist in your codebase. Conventions which exist in your language or framework are less essential to follow, but also recommended.

Separation of concerns

Separation of concerns means to organise functionality well in code.

Code should be separated into sensible units (modules, classes, functions and methods). Someone looking at the code should immediately understand what the particular unit does.

For example, if you have a Circle class, an Enumerable interface or a Math object or module, you tend to have a pretty good idea of what each does and contains. You would expect to find Math.PI, or Math.pow(base, exponent) (these methods exist in the JavaScript Math object). However, you wouldn't expect to find Math.printHelloToTheScreen() or Math.produceAccountingReport(). The methods in the latter example would be unexpected, which would break the principles of KISS and least astonishment.

In addition, units should be small and only do one thing (also known as the single responsibility principle). Another way of thinking about this is that different concerns should be separated at a granular level.

For example, you shouldn't have a god-class called Shape that has functionality for all possible shapes within it. Instead, you should have a small class for each shape.

This code is the bad version:

// Bad god class

class Shape {
  constructor(typeOfShape, length1, length2 = null) { // length2 is an optional parameter
    this.type = typeOfShape;
    if (this.type === 'circle') {
      this.radius = length1;
    } else if (this.type === 'square') {
      this.width = length1;
    } else if (this.type === 'rectangle') {
      this.width = length1;
      this.length = length2
    }
    // And so on for many more shapes
  }

  getArea() {
    if (this.type === 'circle') {
      return Math.PI * this.radius ** 2;
    } else if (this.type === 'square') {
      return this.width * this.width;
    } else if (this.type === 'rectangle') {
      return this.width * this.length;
    }
    // And so on for many more shapes
  }
}

This is the good version:

// Good small and simple classes

class Circle {
  constructor(radius) {
    this.radius = radius;
  }
  getArea() {
    return 2 * Math.PI * this.radius;
  }
}

class Rectangle {
  constructor(width, length) {
    this.width = width;
    this.length = length;
  }
  getArea() {
    return this.width * this.length;
  }
}

Here is another example.

This code is the bad version:

// Function does too many things

function sendData(data) {
  const formattedData = data
    .map(x => x ** 2)
    .filter(Boolean)
    .filter(x => x > 5);

  if (formattedData.every(Number.isInteger) && formattedData.every(isLessThan1000)) {
    fetch('foo.com', { body: JSON.stringify(formattedData) });
  } else {
    // code to submit error
  }
}

This code is the better version:

// Functionality is separated well over multiple functions

function sendData(data) {
  const formattedData = format(data);

  if (isValid(formattedData)) {
    fetch('foo.com', { body: JSON.stringify(formattedData) });
  } else {
    sendError();
  }
}

function format(data) {
  return data
    .map(square)
    .filter(Boolean)
    .filter(isGreaterThan5);
}

function isValid(data) {
  return data.every(Number.isInteger) && data.every(isLessThan1000);
}

function sendError() {
  // code to submit error
}

The idea that you should have small, specific units applies to all code.

Advantages of small units

Smaller, more specific units, have multiple advantages.

Better code organisation

Technically, with the god-class Shape, you know where to go to find the circle functionality, so the organisation is not too bad.

But, with the more specific units of Circle and Rectangle, you can find functionality faster and easier.

It's less obvious with the sendData example, but the same thing applies. Say you want to find the functionality for validating the data. You can find that instantly in the second version. There is a function clearly named isValid. sendData also calls isValid(formattedData), which labels where the data is validated.

However, in the first version of sendData, you'll have to spend more time reading through the details of sendData to find it. Also, the part where the data is validated isn't labelled. You'll have to both parse the code and recognise the line which does the data validation. If you're not familiar with the code, this may be difficult.

In summary, smaller units provide better organisation.

Simplicity and understandability

If you examine the Shape example, you'll see that the code there is quite long and complex. It's difficult to follow. In comparison, the classes Circle and Rectangle are super simple. As a result, they're much easier to understand.

In the sendData example, understanding what sendData does is easier in the second version. It almost reads like English:

Format data
If the data is valid: fetch
Else: sendError

You also don't have to read the implementation of the separate functions, such as isValid, because their names tell you what they do.

All of the smaller functions are simpler too. They are clearly labelled (which helps you understand them even if the implementation is complicated) and they only do a small thing.

In general, smaller units have less code and do less things. This applies the KISS principle, which makes code easier to read and understand.

Easier changes

Code that does fewer things is easier to change than code which does many things.

At the very least, the code you need to change isn't surrounded by other code that you need to carefully avoid changing. Also, you need to understand the code before changing it, which is easier with small units.

Consider the god-class Shape example. The code for the functionality of all the shapes is entangled together. If you try to change the code for the circle, you could accidentally modify something else and create a bug. Also, the functionality for circle exists in multiple different methods inside Shape. You'll have to jump around and change multiple different things.

On the other hand, Circle and Rectangle are very easy to change. Unrelated code is nowhere to be found. You can't break any other shape by accident.

The same applies to the sendData example.

In the second version, if you want to change the data validation, you change the code in isValid and you're finished. You can't break any unrelated code, because there isn't any.

However, in the first version, since a lot of unrelated code is placed together, you might accidentally change something else by accident.

Easier to test

In general, if a unit does less stuff, it's easier to test than if it does more stuff.

Easier to reuse

If a unit does one specific thing, it's immediately reusable any time you need that one thing. However, if a unit does 10 things, or even 2 things, it's generally not reusable unless you need all of those things.

How to apply separation of concerns

To apply separation of concerns, you extract functionality.

For example, with Shape, if you extract all of the relevant code for the circle functionality into its own class, you end up with Circle.

Here is a more step-by-step process.

Here is Shape again for reference.

class Shape {
  constructor(typeOfShape, length1, length2 = null) { // length2 is an optional parameter
    this.type = typeOfShape;
    if (this.type === 'circle') {
      this.radius = length1;
    } else if (this.type === 'square') {
      this.width = length1;
    } else if (this.type === 'rectangle') {
      this.width = length1;
      this.length = length2
    }
    // And so on for many more shapes
  }

  getArea() {
    if (this.type === 'circle') {
      return Math.PI * this.radius ** 2;
    } else if (this.type === 'square') {
      return this.width * this.width;
    } else if (this.type === 'rectangle') {
      return this.width * this.length;
    }
    // And so on for many more shapes
  }
}

Let's define a class called Circle.

class Circle {}

From Shape, let's extract only the constructor functionality that's relevant to circle. That's the part inside the constructor method and inside the if (this.type === 'circle') conditional.

class Circle {
  constructor(radius) {
    this.radius = radius;
  }
}

Repeat for the getArea function:

class Circle {
  constructor(radius) {
    this.radius = radius;
  }

  getArea() {
    return Math.PI * this.radius ** 2;
  }
}

And so on for all the other methods which might be in Shape. Afterwards, repeat for the other shapes.

The same process applies for sendData, although in this case we're not completely replacing sendData like we did with Shape and Circle. Instead, we're extracting functionality into separate functions and calling them inside sendData.

For example, the code to format data was moved into the formatData function and the code to check if the data is valid was moved into the isValid function.

When to apply separation of concerns

Now that you understand the "why" and "how" of separation of concerns, when should you apply it?

Generally, you want "small, specific units that only do one thing".

However, the definition of "one thing" varies, it depends on context.

If you were to show the god-class Shape to someone, they might rightfully say that it only does one thing. "It handles shapes".

Someone else may say that Shape does a lot of things. "It handles circles, rectangles and so on. That's multiple things".

Both claims are correct. It all depends on what level of abstraction you consider.

In general, it's good to consider small levels of abstraction. You want units that do small, specific things.

That's because, as already examined, smaller units have more benefits than larger units.

So, here are some guidelines.

When code feels large and complicated

If you feel that some code is difficult to understand, or too large, try extracting some units out of it.

Can you keep extracting?

Robert Martin has a technique that he calls "extract till you drop".

In short, you keep extracting functionality until there is no reasonable way of extracting any more.

As you write code, consider: "Can I extract some more functionality from this unit, into a separate unit?"

If it's possible to extract further, then consider doing so.

See Robert Martin's blog post on extract till you drop for more information on this technique.

Reasons to change

Consider, what reasons does this code have to change?

Code which is placed together, which has different reasons to change (different parts may change at different times), is bad, as we've already examined.

The solution is to move code with different reasons to change into separate units.

Consider the Shape example. Shape will change when:

anything needs changing for circles
anything needs changing for rectangles
anything needs changing on any other shape
a new shape needs to be added or removed

In the sendData example, sendData could change if:

the formatting of the data needs to change
the validation of the data needs to change
the data in the error request needs to change
the endpoint (URL) of the error request needs to change
the data in the sendData request needs to change
the endpoint (URL) of the sendData request needs to change

All of these reasons are indicators that you may want to separate that functionality.

Who (which role in the company) may want to change this code

This is another flavour of "what reasons does this code have to change".

It asks who (which role in the company) may want to change the code.

In the sendData example:

developers may want to change something about the URL endpoints of the requests or the bodies of the requests
accountants may want to change the data validation in the future
a product owner who uses the submitted data to generate reports could want to format the data differently in the future

Both of these questions (what could change and who may want changes) try to point out different concerns in the code, that may benefit from separation.

Be pragmatic

The final point is to be pragmatic.

You don't have to separate everything to the extreme. The goal is to have code that's easy to work with.

For example, you don't need to enforce every function in your codebase to be at maximum 4 lines long (which is possible to do). You would end up with hundreds of miniscule functions. They may be harder to work with than more reasonably sized functions, that are an average of 4 to 8 lines long.

Principle of least knowledge

In software, it's beneficial to minimise knowledge. This includes the knowledge that code has of other code (dependencies), as well as the knowledge you need to work with particular areas of code.

In other words, you want software to be decoupled and easy to work with. Making changes shouldn't break seemingly unrelated code.

Knowledge in code

In programming, knowledge means dependencies.

If some code (call it module A), knows about some other code (call it module B), it means that it uses that other code. It depends on it.

If some code is being used elsewhere, that means that there are limitations on how you can change it, otherwise you would break the code that uses it.

Without discipline and control, this is where you can get into a chain reaction of propagating changes. The situation where you just wanted to make a small change and had to modify every file in the system to do so. You changed A, which was used by B and C so you had to change both of those to accommodate your changes to A. In turn B and C were used in other places which you also had to change. And so on.

Every change is error-prone, multiple cascading changes are much worse.

Additionally, you need to actually remember or know that these dependencies exist. This is quite difficult to do, especially when dependencies propagate far and wide throughout your code. But if you don't remember, you won't make all of the required changes and you'll immediately introduce bugs.

That's why you need to minimise knowledge in your code.

Modifications to code

Here are the possible changes you can make to already-existing code.

No change to contract

The only change you can make with no propagating changes, is a change that doesn't affect anything else in the codebase.

For example:

// Original
function greet(name) {
  return 'Hello ' + name;
}

// After change
function greet(name) {
  return `Hello ${name}`;
}

These two functions are equivalent from a caller's point of view. They have the same contract. If you change from one version to the other, nothing else in the codebase needs to change, because nothing could possibly be affected by this change.

Changing the contract of a "private" function

The next best case is when you change the contract of a private function. Something that's not public to the majority of the codebase. In this case, if you change the contract, the code that is affected is very small.

For example, consider this Circle class:

// Circle.js
class Circle {
  constructor(radius) {
    this.radius = radius;
  }

  getArea() {
    return _privateCalculation(this.radius);
  }
}

function _privateCalculation(radius) {
  return Math.PI * radius ** 2;
}

export default Circle;

Next, consider that we want to delete _privateCalculation. Here is the code after the change:

// Circle.js
class Circle {
  constructor(radius) {
    this.radius = radius;
  }

  getArea() {
    return Math.PI * this.radius ** 2;
  }
}

export default Circle;

When we deleted _privateCalculation, getArea was affected. As a result, we also had to modify getArea to accommodate the changes. However, since _privateCalculation wasn't used anywhere else in the codebase and since getArea didn't change its contract, we're finished. Nothing else in the codebase needs to be modified.

Changing the contract of a public function

The pattern continues in the same way. If you change the contract of anything, you'll have to modify everything that uses it to accommodate. If you change more contracts as a result, you'll have to modify even more things. And so on.

For example, if you delete getArea, you'll have to update all of the code in the codebase that uses it. Since getArea is a public function, many things could be using it.

In general, you want to prevent these situations.

The only real way to prevent them is to separate concerns properly. You need to organise your code into sensible units that make sense for your project. If done well, that minimises the chance that you'll need to change the contract of those units in the future.

For example, what is the chance that the Circle class needs to change its contract? It's very low.

Other than that, keep everything you can private, so that very little is affected when you need to change code.

Now, changes to public things are necessary sometimes. That's life. It could be due to new requirements, or due to large refactors. You'll deal with them when you need to, but hopefully it won't be too often.

More tips

The principle of least knowledge has many more applications. They all deal with making code independent to changes and with minimizing the mental knowledge you need to work with code.

Other applications of this principle include:

the interface segregation principle. This keeps interfaces small. It means that code which uses an interface depends on less things. It allows for easier future changes such as splitting a class based on its interfaces or creating a smaller separate class for an interface.
the law of Demeter. This prevents functions / methods from depending on long chains of object compositions.
immutability. This eliminates changes to variables. It means that you don't need to track how the variable has changed over time. It reduces the knowledge you need to work.
only accessing things in the local scope (or maybe instance scope). Global things are accessible by many things in the codebase. Changing them may break many things. It's also difficult to track how they change over time, because many things can change them. However, local things are more "private". This makes tracking changes easier.

Abstraction and don't repeat yourself (DRY)

DRY (don't repeat yourself) is a core principle in programming.

It says that if you have multiple instances of similar code, you should refactor them into a single abstraction. That way you'll end up with just one instance of the code, rather than multiple.

To accommodate the differences, the resulting abstraction accepts arguments.

Motivation for DRY

One of the reasons for DRY is to cut down the time you need to write code. If you already have an abstraction for X functionality, then you can import it and use it, rather than re-code it from scratch every time you need it.

Another reason is to make changes easier. As already mentioned, we're bad with repetitive work. If code is DRY, then you only have to make a specific change in one place. If code isn't DRY then you have to make a similar change in multiple places. Making a single change is safer and faster than making multiple similar changes.

Additionally, keeping code DRY applies separation of concerns. The abstraction will have to be placed in a sensible place in the codebase (good for code organisation). Also, the implementation of the abstraction is separated from the caller.

How to apply abstraction and DRY

Here are some guidelines for applying DRY.

Combine similar code into a single abstraction

Whenever you find multiple instances of the same or similar code, combine them into a single abstraction. If there are slight differences between the instances, accept arguments to handle them.

You've probably done this a vast number of times throughout your career.

To illustrate the point, let's use the function map as an example. map is a function that handles this common process:

Create a new, empty, array
Iterate over an array with a for-loop
Run some functionality on every value
Push the resulting value to the new array
After the for-loop ends, return the new array

This process is very common. It appears all the time in many codebases.

Here is what it normally looks like using a for-loop.

function double(x) {
  return x * 2;
}

function doubleArray(arr) {
  const result = [];
  for (let i = 0; i < arr.length; i++) {
    const element = arr[i];
    const transformedElement = double(element);
    result.push(transformedElement);
  }
  return result;
}

const arr = [1, 2, 3, 4];
const result = doubleArray(arr);

In addition to the function doubleArray, there would be many other functions that are almost exactly the same. The only differences would be the array they iterate over and the transformation they make on each element.

So, take the common parts from those functions and put them into a separate function called map. Accept arguments for the things that are different every time, the array and the transformation to run on each element.

Here is the resulting code.

function map(array, transformationFn) {
  const result = [];
  for (let i = 0; i < array.length; i++) {
    const element = arr[i];
    const transformedElement = transformationFn(element);
    result.push(transformedElement);
  }
  return result;
}

Then, in every function in your codebase similar to doubleArray, use map instead.

function double(x) {
  return x * 2;
}

function doubleArray(arr) {
  return map(arr, double);
}

const arr = [1, 2, 3, 4];
const result = map(arr, double);

(Of course, arrays in JavaScript already have a built-in method for map, so you wouldn't need to create a standalone map function. This was just for illustrative purposes.)

You can do the same with any other code. Any time you encounter similar code, combine it into a single abstraction and accept arguments for any differences.

Rule of three

The rule of three is a precaution against combining functionality too early.

It states that you should combine functionality into a single abstraction if there are three occurrences of it. Don't combine if there are only two occurrences.

That's because the instances of code you might combine, may diverge (each may change differently) in the future.

For example, consider this code:

function validateUsername(str) {
  return str.length >= 6;
}

function validatePassword(str) {
  return str.length >= 6;
}

It would probably be a mistake to combine the duplicate functionality into its own abstraction, like so:

// combined too early

function validateUsername(str) {
  return validate(str);
}

function validatePassword(str) {
  return validate(str);
}

function validate(str) {
  return str.length >= 6;
}

The problem is that, in the future, validateUsername and validatePassword may change differently. It's not difficult to see how that may happen.

For example, in the future, validateUsername may need to check that there are no special characters, while the password may require special characters.

Obviously you could make both scenarios work in the validate function using conditionals, but it would be messier than if you had kept the functionality separate.

This is why we use the rule of three. Waiting until the third occurrence makes it more likely that the similar functionality is significant rather than coincidental. It means that things are less likely to diverge in the future.

It also makes it so that if one of the three instances of similar code diverges, you can separate it and still keep the abstraction for the other two. On the other hand, if you combined functionality on the second occurrence, then had to separate them out again, you would have to revert both of them.

In summary, refactoring on the second occurrence is more likely to be a waste of time.

Of course, the rule of three is just a guideline. Remember to be pragmatic and do what's best for your project. Some similar instances of code may be changing in the same way every time. Or maybe they are each quite complicated to change, and you have to make a similar change to both every time. In that case, it may be more beneficial for your project to combine them into a single abstraction, even if you have to ignore the rule of three.

Side effects

The last thing we're going to look at is side effects. These aren't a single principle, but a combination of many principles + being pragmatic.

(And no, they're not just the domain of functional programming. It's essential for all code to handle side effects properly.)

In programming, the general definition of a side effect is anything that changes the state of the system. This includes:

changing the value of a variable
logging to the console
modifying the DOM
modifying the database
any mutation whatsoever

It also includes "actions" that may not be viewed as mutations, such as sending data over the network.

I also say that accessing non-local scope is a side effect. It may not be in the official definition, but it's as unsafe as other side effects, especially if the variable you're trying to access is mutable. After all, if you access a global variable whose value isn't what you expect, you have a bug, even if the code in question doesn't modify it.

All code needs "side effects" to be useful. For example, you have to modify the database or the DOM at some point.

But side effects can be dangerous. They need to be handled carefully.

The danger of side effects

Side effects are not directly harmful, but they can be indirectly harmful.

For example, code A and B might both depend on the value of a global variable. You might change the value of the global variable, because you want to influence code A. But, you don't remember that code B will be affected as well. As a result, you now have a bug.

These hidden dependencies, where you change one thing and something else breaks, can be very difficult to remember, track and manage.

Another example is changing the DOM. The DOM can be thought of as just a global object with state. The problem is that, if different pieces of code affect the DOM at different times, in non-compatible ways, there can be bugs. Maybe code A depends on element X to be there, but code B deleted that entire section altogether just before code A ran.

Perhaps you've encountered bugs like these in your work as well.

Additionally, side effects break most of the principles we've covered so far:

KISS and the principle of least astonishment
principle of least knowledge (because code affects other, seemingly unrelated code)
separation of concerns (because concerns are not necessarily self-contained or well-organised)

One important thing to understand however, is that side effects are not inherently harmful. They only cause bugs if we code them incorrectly. They are code we write which happens to be incompatible with other code we write. We write code A and then we write code B which breaks code A under certain circumstances.

The main danger of side effects is that they're generally very difficult to track. The reason for that is because tracking global state, which anything can modify at any time, is very difficult. If uncontrolled, how could you possibly track changes made to the DOM over time? You may have to track so many things that it just wouldn't be feasible.

Asynchronicity and race conditions also add to the complexity and difficulty of tracking side effects.

Another downside of side effects is that code with side effects is generally harder to test.

Handling side effects

Even though side effects are dangerous, they can be handled effectively.

Be pragmatic

The most important point, as always, is to be pragmatic.

You don't have to avoid all side effects to the extreme. You are only required to be careful with potentially incompatible code.

For example, immutability is a good way to avoid many types of side effects. However, immutability makes little difference in the local scope of functions.

For example, here are two functions that do the same thing. One uses immutability and the other doesn't.

function factorial1(n) {
  let result = 1;
  for (let i = 1; i <= n; i++) {
    result *= i;
  }
  return result;
}

function factorial2(n) {
  if (n <= 1) {
    return 1;
  }
  return n * factorial2(n - 1);
}

In the example, factorial1 uses mutation. The values of result and i both change during execution.

factorial2 uses immutability. The values of the variables inside it never change during function execution.

But it makes no difference. Other than some language limitations of recursion (which we'll ignore for this example), for all intents and purposes, factorial1 and factorial2 are exactly the same from the perspective of the caller.

In fact, people tend to be less comfortable with recursion, so factorial2 could actually be the worse choice depending on your team.

So be pragmatic and do what's best for your project.

Immutability

Having said that, immutability is an easy way to avoid a large portion of side effects.

By never modifying variables in your code unnecessarily, you remove a large problem. You won't have things changing unexpectedly. You also won't have to track the lifecycle of variables to know what values they contain.

When starting with immutability, start simple. Then, over time, try to make as many things immutable in your work as possible.

Instead of modifying a variable, create a new variable for the new value. Instead of modifying an object, create a new object with the new values you want.

For example:

// Example 1 - Don't do this
function doubleArray(array) {
  for (let i = 0; i < array.length; i++) {
    array[i] = array[i] * 2; // mutates the original array
  }
}
const arr = [0, 1, 2, 3];
doubleArray(arr);

// Example 2 - Do this
function double(x) {
  return x * 2;
}
function doubleArray(array) {
  return array.map(double); // returns a new array, without modifying the original
}
const arr = [0, 1, 2, 3];
const result = doubleArray(arr);

In example 1, the original array is modified.

In example 2 the original array is not modified. doubleArray creates and returns a new array with the doubled values. Outside of the function, we create the new variable result to hold the new array.

Immutability performance concerns

Immutability may be slightly worse for performance. However, you probably shouldn't worry about that, because:

you shouldn't do premature optimisation for performance. Don't worry about performance except for the bottlenecks in your code.
in most cases, immutability won't have a significant impact on performance
you can use a performant immutable data structures library, such as Immer for JavaScript. It converts some operations from Big-O(n) time (such as copying an entire object) to Big-O(1) time.
you can be pragmatic. You don't have to apply immutability in places where it would bottleneck performance.

Also, in some cases, immutability can improve performance by making things easier to run in parallel.

Avoid non-local scope

Avoid accessing or modifying things that are not exclusively in the local scope of your functions or methods. This means that it's probably okay to modify variables that originated in your local scope, but not variables which were passed in as arguments (originated outside of the local scope).

If necessary, it's alright to mutate things up to instance or module scope.

The further away from local scope you go, the more dangerous it gets, because things become more global. This makes things harder to track and introduces far-reaching dependencies in your code.

Wherever possible:

pass things in explicitly as arguments
stick as close to local-scope as possible

For example:

// Example 1 - Don't do this
function doubleResult() {
  result *= 2; // Accesses and mutates a variable outside of the local scope
}
let result = 5;
doubleResult();

// Example 2 - Do this
function double(n) {
  return n * 2; // Accesses parameter which is in local scope. Doesn't mutate anything
}
const initialValue = 5;
const result = double(initialValue);

In example 1, doubleResult accesses result, which is a variable outside of its local scope. It also mutates it, changing its value. Now, if any other code in the codebase accesses result, it will see the new value.

In example 2, double only accesses its parameter, which is part of its local scope. It doesn't mutate any values outside of its local scope.

In a real codebase, something resembling example 1 could be very difficult to track. The result variable may be defined much further away from both the doubleResult function as well as the function call. This makes it harder to track the value of result.

Also, if result isn't what you expect, you have a bug. For example, you may have already called doubleResult 3 times but you may not remember.

Overall, in example 1, you can't predict what a function that uses result will do unless you know the exact value of result at that time. To do this, you'll need to search and trace through the entire codebase to keep track of result at all times.

In the second example, initialValue is always 5, so there are never any surprises. Also you can see what the function is doing immediately and can easily predict what will happen.

Be extremely careful

Sometimes you can't just rely on immutability. For example, at some point, you must mutate the DOM or the database, or make a call to a third party API, or run some sort of side effect. As already mentioned, asynchronicity only adds to the problem.

In this case, you just have to be extremely careful.

Side effects are probably where the majority of the bugs in your codebase exist. They're the hardest code to understand and track.

Regardless of what you do to try and manage them, you must always invest the required time and attention to them.

Separate pure and impure functionality

For the most part, try to separate code with side effects and code without side effects. Your functions shouldn't both perform side effects and have "pure" code. They should do one or the other (within reason).

This is also known as the command-query separation principle. It's also an application of separation of concerns.

For starters, something like writing to the database is very different to calculating what to write to the database. Those two concerns can change independently and for different reasons. As we examined in separation of concerns, they should be separated.

Further, pure functions are generally easy to understand, reuse and test. Functions with side effects are not. Therefore, for your codebase to be easy to work with, you probably want as many functions as possible to be pure. This means that you should separate your pure functionality from your side effects.

For example, instead of this:

function double(x) {
  return x * 2;
}

function doubleArrayAndDisplayInDOM(array) { // this function does a non-trivial calculation / operation and performs a side effect
  const doubled = array.map(double); // (pretend this is a non-trivial calculation / operation)
  document.querySelector('#foo').textContent = doubled; // writing to the DOM is a side effect
}

function main() {
  doubleArrayAndDisplayInDOM([1, 2, 3, 4]);
}

Do this:

function double(x) {
  return x * 2;
}

function doubleArray(array) { // this function only does a calculation / operation
  return array.map(double);
}

function displayInDom(content) { // this function only performs a side effect
  document.querySelector('#foo').textContent = content;
}

function main() {
  const doubled = doubleArray([1, 2, 3, 4]);
  displayInDom(doubled);
}

Clear areas of responsibility

As much as possible, you need to make sure that your code doesn't have conflicts. Code which performs side effects shouldn't conflict with other code performing other side effects at different times.

A good way to do this is to have distinct areas of responsibility in your code.

For example, if code A modifies element X in the DOM, then it should ideally be the only code which modifies that part of the DOM. All other code that needs to influence X should talk to code A to do so. That way tracking changes to element X is as easy as possible.

Additionally, try to organise code dependencies well. For example, code A shouldn't run if any other code runs which would conflict with it. Also, code A shouldn't run if the state that it depends on isn't there or isn't what code A expects.

Side effects in pairs

For side effects which come in pairs (e.g. open / close file), the function that started the side effect should also finish it.

For example, instead of this:

/* Note, this is pseudocode */

function openFile(fileName) {
  const file = open(fileName);
  return file;
}
const file = openFile('foo.txt');

/* Lots of other code in-between */

doStuffToFile(file);
close(file);

Do this:

/* Note, this is pseudocode */

function useFile(fileName, fn) {
  const file = open(fileName);
  fn(file);
  close(file);
}
useFile('foo.txt', doStuffToFile);

Robert Martin calls this technique "passing a block". The function useFile both opens and closes the file, so it doesn't leave an open file pointer in the system.

This ensures that the file will be closed when it's no longer needed.

As for the functionality to perform on the file, that's passed into the function. It's the parameter fn.

This ensures that you won't forget to finish the side effect later. It also provides good code organisation and makes the code easy to understand and track. The entire side effect is fully handled in one place.

Consider using a framework or functional programming language

As with immutability, the best option might be to avoid side effects as much as possible.

To help with this, you can consider delegating some of them to a framework, library, or functional programming language.

For example, for working with the DOM, you can use a library such as React (or one of the many alternatives).

Something like React handles all of the DOM-related side effects. Then, in your application, you just write pure functions. You don't modify the DOM directly. Instead, your functions generate an object that represents what the DOM should look like.

This is good for you, because working with pure functions is much easier than working with side effects.

As for actually modifying the DOM, those side effects still occur, but they're React's problem now.

Additionally, the parent / child hierarchy of React ensures that your DOM manipulations won't conflict with each other and cause problems. For example, React code involving element X won't run if element X won't actually exist. This is an example of good organisation and structure in your code to prevent conflicts with other side effects.

Of course, there are many more pros and cons to using something like this. But it's just an option for you to consider.

Challenge - Function that only runs with no arguments (intermediate / advanced functional programming)

Spyros Argalias — Tue, 04 May 2021 09:59:27 +0000

This is an intermediate / advanced functional programming challenge I had to solve in an interview. I found it very interesting and it had me thinking for a while.

If you're interested in a brain teaser, have a go. You can also complete it using classes and methods if you prefer, but we'll use functions in this article.

(If you don't know a lot about functional programming and want to look at that first, then check out functional programming - the ultimate beginner's guide.)

The challenge

There were two parts to the challenge. Part 1 and part 2. Each part increases in difficulty.

I've also added a small part 3.

Challenge, part 1

Design a function that you can keep calling in a chain as long as you keep passing in arguments. For example, foo(argument1)(argument2). During this time, it shouldn't do anything except collect the arguments. Finally, when you call the function without an argument, it should call a real function, such as console.log, with the arguments you've passed in so far.

Here is a code example showing how this function should behave:

foo('a'); // nothing happens
foo('a')('b'); // nothing happens

foo(); // logs an empty line (calls console.log())
foo('a')(); // logs 'a' (calls console.log('a'))
foo('a')('b')() // logs 'a b' (calls console.log('a', 'b'))
foo('a')('b')('c')() // logs 'a b c' (calls console.log('a', 'b', 'c'))'

// optionally, the function can accept more than one argument at once
foo('a', 'b')() // same as foo('a')('b')()
foo('a')('b', 'c')() // same as foo('a')('b')('c')()

Challenge, part 2

Implement a function similar to question 1, but make it "stateless"?

Different function calls shouldn't share state with each other.

For example:

const a = foo('a');
const ab = a('b');
const abc = ab('c');

a(); // logs 'a' (calls console.log('a'))
abc(); // logs 'a b c' (calls console.log('a', 'b', 'c'))
ab(); // logs 'a b' (calls console.log('a', 'b'))

The difference compared to part 1, is that calling a('b') shouldn't also add the argument 'b' to the call for a(). a() should log 'a', not 'a b'.

Challenge, part 3

Make a function similar to the one for part 2, but the first time it's called it must be called with a single argument. That argument should be the function it will run in the end.

Then, as normal, the function should keep accepting and collecting arguments. When it's finally called without an argument, it should execute the function you passed in as the first argument with the arguments it has collected.

For example:

const log = actWhenCalledWithoutArguments(console.log);
const a = log('a');
const ab = a('b');
const abc = ab('c');

log(); // logs an empty line (calls console.log())
a(); // logs 'a' (calls console.log('a'))
abc(); // logs 'a b c' (calls console.log('a', 'b', 'c'))
ab(); // logs 'a b' (calls console.log('a', 'b'))

Hints - Part 1

So what would your solution to these questions be? Before reading on, try solving them on your own.

If you need help, read on for some hints.

Hint 1 - Currying

For the first hint, notice that these functions sound a lot like currying. Curried functions also accept arguments multiple times, before finally executing the "real functionality" with all of the arguments they've collected. This is very similar to what you're trying to do in this challenge.

In particular, the curry utility seems very relevant. That's a function that takes a normal function, which isn't curried, and turns it into a curried function. In its implementation, it has a mechanism for storing arguments and then calling a function with all of the stored arguments later.

So, you may want to start by implementing the curry utility first. Looking at its source code may be helpful for the challenges.

Feel free to try to implement it yourself.

Otherwise, here is an example implementation:

function curry(fn, arity = fn.length) {
  function execute(...args) {
    if (args.length === arity) {
      return fn(...args);
    }
    function gatherMoreArgs(...moreArgs) {
      return execute(...args, ...moreArgs);
    }
    return gatherMoreArgs;
  }
  return execute;
}

// example usage
function foo(a, b, c, d) {
  console.log(a, b, c, d);
}

const curriedFoo = curry(foo, 3);
curriedFoo('a')('b', 'c')('d'); // logs 'a b c d' (console.logs('a', 'b', 'c', 'd'))

Hint 2 - More functions

For the challenges, you don't need to have just one top-level function. Just like the curry utility, you can have more functions. The curry utility itself is made up of 3 nested functions in total.

If you're stuck on your solution, explore what you can do with 1 function, 2 functions or even 3 functions, nested or not.

Hint 3 - How to gather arguments for part 1

This hint is more spoiler-heavy. It talks about a possible implementation for part 1.

One way to gather the arguments is to have an array. Then, every time the function is called with arguments, push them to that array.

Solution - Part 1

Alright, if you're ready, here's the solution for part 1:

const logWhenCalledWithoutArguments = (...args) => {
  const argsSoFar = [];

  const execute = (...moreArgs) => {
    if (moreArgs.length === 0) {
      console.log(...argsSoFar);
    } else {
      argsSoFar.push(...moreArgs);
      return execute;
    }
  }

  return execute(...args);
}

logWhenCalledWithoutArguments is a higher order function (a function that returns another function). This is needed so that it can create a private array (argsSoFar), that exists only for that invocation of logWhenCalledWithoutArguments. That way, different calls of logWhenCalledWithoutArguments won't share the same arguments.

Other than that, the execute function does the real work. First, it checks whether it was called without arguments. If that's the case, then it calls console.log with all of the arguments collected so far. Otherwise, it adds the new arguments to argsSoFar. Then, it returns itself so that the user can call the function again and keep providing arguments.

At the end of logWhenCalledWithoutArguments, we immediately call the execute function and return its result. That way, we start checking and collecting arguments from the first call.

Hint - Part 2 - Making it stateless

This is another spoiler hint.

Part 2 of the solution can't share state like part 1 did. With the solution for part 1, this code wouldn't work:

const a = logWhenCalledWithNoArguments('a');
const ab = a('b');
a(); // incorrectly logs 'a b'
ab(); // correctly logs 'a b'

So you can't use a shared array like in part 1.

Instead, you have to find a way to pass in the arguments across different calls using closures.

Solution - Part 2

Alright, if you're ready, here's the solution to part 2.

const logWhenCalledWithoutArguments = (...firstArgs) => {
  const gatherArgs = (...args) => {
    const execute = (...moreArgs) => {
      if (moreArgs.length === 0) {
        return console.log(...args);
      }
      return gatherArgs(...args, ...moreArgs);
    }
    return execute;
  }
  const firstExecute = gatherArgs();
  return firstExecute(...firstArgs);
}

This function has a lot of similarities to the solution for part 1. The main difference is that, instead of capturing arguments in an array, we use the function gatherArgs to hold the arguments.

Also, just like before, we run the execute function straight away, to check if we got an argument on the first call.

Solution - Part 3

For part 3, the first call must be a single argument, the function to execute at the end. Everything else is the same.

If you're ready, here's the solution:

const actWhenCalledWithoutArguments = (fn) => {
  const gatherArgs = (...args) => {
    const execute = (...moreArgs) => {
      if (moreArgs.length === 0) {
        return fn(...args);
      }
      return gatherArgs(...args, ...moreArgs);
    }
    return execute;
  }
  return gatherArgs();
}

The solution is very similar to the solution for part 2.

The main difference is that we don't need to check for an argument on the first call. As a result, we don't need to run execute straight away. All we have to do is return it.

The other difference is that we replace the call to console.log with fn (the first argument).

Other than that, everything else is the same.

Final notes

Anyway, that's it for this challenge.

I hope you enjoyed it.

Let me know if you completed it, and whether you thought it was easy or difficult, in the comments. It's not the kind of thing you have to implement at work every day.

Also, if you have any similar challenges, or if you have any tips or feedback for this one, then please leave a comment.

Alright, see you next time.

How to write clean code units (functions and methods)

Spyros Argalias — Mon, 26 Apr 2021 17:35:16 +0000

Code units at the edges of your application should be small, independent and only do one thing.

This is a direct application of many established programming principles. This includes KISS, separation of concerns, single responsibility principle and many more.

So, to have "good code", apply this principle where possible.

This article will show you how to apply it. It will also examine why this principle is important and how it makes your code better.

To showcase, we'll use units at the edge of an application. They're easier to use to illustrate this point. But, after you learn the guidelines, you can apply them to any kind of code unit.

Overall, the main point of this article can be summarized in the following example. Example 1 has a large makeRequest function, which is worse than example 2. In example 2, that function has been separated into two smaller and more specific functions.

Example 1, the bad version:

function main() {
  const data = getData();
  makeRequest(data);
}

function makeRequest(data) {
  if (isValid(data)) {
    fetch('https://myfakeapi.com/', {
      method: 'POST', body: JSON.stringify(data)
    });
  } else {
    fetch('https://errormonitoringservice.com/', {
      method: 'POST', body: JSON.stringify(data)
    });
  }
}

Example 2, the good version:

function main() {
  const data = getData();
  if (isValid(data)) {
    makeRequest(data);
  } else {
    reportError(data);
  }
}

function makeRequest(data) {
  fetch('https://myfakeapi.com/', {method: 'POST', body: JSON.stringify(data)});
}
function reportError(data) {
  fetch('https://errormonitoringservice.com/', {method: 'POST', body: JSON.stringify(data)});
}

Let's examine why example 1 is worse.

Note: In this article, a unit refers to a function / method / module / class. We'll be using functions, but any of them can be used.

Small, independent units

An "edge" unit of code is a fairly small piece of functionality that doesn't have any dependencies. It does some fairly low-level stuff and it doesn't call any other functions to help it. It's at the extremities, the very edges, of your application.

It's safe code that you call to help you do something.

When you call it, you know what it's going to do and you know that it's not going to break anything.

It should be like a well-tested library that you've imported into your project. It does something small and specific and you expect it to work 100% of the time.

To do that, these kinds of units:

should be small
should only do one small, specific thing
should be independent
shouldn't have side effects, unless the only purpose of the unit is to perform a side effect

Examples of good code units

Here are some examples of these kinds of good units:

function add(a, b) {
  return a + b;
}

function getProperty(object, propertyName) {
  return object[propertyName];
}

function appendElementToBody(element) {
  document.body.append(element);
}

function doubleSpeed(gameObject) {
  gameObject.speed = gameObject.speed * 2;
}

function incrementSpeedDamaged(gameObject) {
  gameObject.speed = gameObject.speed + 0.5;
}
function incrementSpeed(gameObject) {
  gameObject.speed = gameObject.speed + 1;
}

Notice that these units:

don't have conditionals (if / else statements)
do very little
don't read / write to anything except their parameters (except for appendElementToBody, because the document object is a global singleton)
only have side effects if they do nothing else

In comparison, here are some units that don't follow these guidelines:

const valueToAdd = 5;
function add(x) {
  return valueToAdd + x;
}

const object = {/* has some properties here*/};
function getProperty(propertyName) {
  return object[propertyName]
}

function appendElementToBody(element) {
  if (element.id === 'foo') {
    return; // do nothing
  }
  document.body.append(element);
}

let shouldDouble = true;
function doubleSpeed(gameObject) {
  if (shouldDouble) {
    gameObject.speed *= 2;
  })
}

function incrementSpeed(gameObject, isDamaged) {
  if (isDamaged) {
    gameObject.speed += 0.5;
  } else {
    gameObject.speed += 1;
  }
}

We'll examine each of them in detail, including what makes them good or bad.

But first, let's examine the advantages and disadvantages of the guidelines in general. What are the benefits that you gain from the good code examples, rather than the bad ones?

Benefits of good code units

If you follow the guidelines, you get the benefits of good code. Things such as:

code that is easy to understand
code that works correctly, predictably, without unintended consequences
code that is easy to reuse
code that is easy to change
code that is easy to test

If you use the bad versions, you get the opposite. Things such as:

code that is harder to understand
code that is not predictable, can have unintended consequences, is harder to track and easier to get wrong
code that is not reusable
code that is brittle and hard to change
code that's much harder to test

Next, let's see how the examples given affect these benefits / disadvantages.

Examining examples of code units and their benefits

Let's go through each example one by one. Some will be more trivial and faster than others.

Example: add

The add function is trivially simple.

function add(a, b) {
  return a + b;
}

However, it showcases the point of good units well. This function is:

extremely simple to understand
reusable every time you need it
extremely easy to test

One thing you may be wondering is "so what"? Why should you have an add function when you can just add things inline when you need to?

Well, let's just say that there are many valid reasons to have one. For example, you may need to pass it into a higher order function like map, or to use partial application.

In addition, add just showcases the principle. Instead of add you might have some real functionality which works exactly like add internally. For example, you may have a function formUserGreeting(username, userFlair), which may concatenate (add) the username and userFlair together.

Here is the bad version of the add code:

const valueToAdd = 5;
function add(x) {
  return valueToAdd + x;
}

This version is much worse.

For starters, it has a weird signature which you might not expect. If you were working in some file foo and you imported this function to use it, you probably wouldn't remember or expect it to work the way that it does. It would confuse you for a moment until you examined the function closer.

This breaks the principle of least astonishment (one of the fundamental principles). When something works differently to how you expect, it's easy to create bugs.

This function is also more difficult to understand. You have to spend additional time to read the source code of this function before you understand how it works.

Also, it's not reusable. It always adds 5 to the number you provide. This means that you can never reuse it unless you want to add 5.

So overall, it's much worse.

To create the good version, make sure that the function it only accesses its local scope. It should receive everything it needs to work as an argument. It shouldn't access anything else.

Finally, it takes no effort to have the better version, so you might as well have it.

Example: getProperty

Next is the getProperty example.

Here is the code for the good version:

function getProperty(object, propertyName) {
  return object[propertyName];
}

Here is the code for the bad version:

const object = {/* has some properties here*/};
function getProperty(propertyName) {
  return object[propertyName]
}

The benefits / disadvantages are the same as the add example.

The good version is:

100% predictable
easy to understand
easy to reuse
easy to test

The bad version has a signature that a developer may not expect until they look at the code. It's also not reusable if you want to work with a different object.

To get the good version, write the function in a way where it doesn't read anything outside of its local scope.

Example: appendElementToDom

Now we're starting to examine functions that may seem more realistic. These are functions that you probably have in your codebase (or something similar to them).

Here is the good version:

function appendElementToBody(element) {
  document.body.append(element);
}

Here is the bad version:

function appendElementToBody(element) {
  if (element.id === 'foo') {
    return; // do nothing
  }
  document.body.append(element);
}

The second version of the code is concerning. It has a conditional that's not obvious to a user of the function unless they look at its source code.

Consider, if you use a function named appendElementToBody, what would you expect it to do?

You would probably expect it to append an HTML element to the body element, 100% of the time, not just some of the time.

Also consider, when you import a library to use in a project, you expect it to do what it says on the tin. You don't expect it to have hidden conditions where it sometimes does what you expect, other times it doesn't do anything and other times it does something different altogether.

The problem with this code is the following scenario:

Tomorrow, you realise that have a bug in your program. It turns out that whenever a user creates a particular todo list item, it doesn't get added to the DOM. Maybe it doesn't get added to the database either (you may have a similar condition there).

In this situation, unless you specifically remember how the appendElementToBody works (read: you already know where the bug is), it will probably take you a few hours to find the bug.

Most likely, you're going to trace the code from the start, from where the user clicks "submit" for the new todo. The appendElementToBody is the last function that gets run, so you might not examine it for a long time.

Now, this example is very small and trivial. It's unlikely that you'll run into trouble for checking if an element has an ID of foo.

But it's not difficult to see how something like this can become a problem under different circumstances. You may have more complicated conditions. You may also have conditions in many functions all over your codebase.

Something, at some point, will cause a bug. In the meantime, there could already be bugs without anyone realising.

Anyway, that's enough of a rant. The point is, don't do this.

Possible improvements

Your unit functions should be 100% predictable and do one small thing. They shouldn't have conditionals in them. That's not their responsibility or where that conditional logic should be.

Most of all, they shouldn't have implicit (unexpected and non-obvious) conditions like this.

Explicit conditionals are at least predictable. Something like this would be better:

function appendElementToBody(element, excludedSelectors) {
  for (let i = 0; i < excludedSelectors.length; i++) {
    const selector = excludedSelectors[i];
    if (document.querySelector(selector)) {
      return; // exit the function and do nothing
    }
  }
  document.body.append(element);
}

A better option may be to change the name of the function so its functionality is obvious:

function maybeAppendElementToBody(element, excludedSelectors) {
  for (let i = 0; i < excludedSelectors.length; i++) {
    const selector = excludedSelectors[i];
    if (document.querySelector(selector)) {
      return; // exit the function and do nothing
    }
  }
  document.body.append(element);
}

In this version, the function acts predictably. It does nothing for particular selectors, but at least you expect that.

But, for the best improvements, consider:

rethinking your program design so you don't need the condition
putting the condition in a higher-level function. "Move the logic up", so to speak, to a more appropriate place.

For example, you could have something like this:

// Extremely simple TODO creator with very basic code

const todos = [];

function handleNewTodoSubmit(event) {
  event.preventDefault();

  // read the DOM to see what the user has typed as the TODO title
  const title = document.querySelector('#todo-input').value;

  // condition is checked here (albeit slightly altered to the original)
  if (!doesTodoTitleAlreadyExist(todos, title)) {
    const todo = createTodoObject(title);
    todos.push(todo);
    displayTodo(todo);
  }
}

function doesTodoTitleAlreadyExist(todos, title) {
  function hasTargetTitle(todo) {
    return todo.title === title;
  }
  return todos.some(hasTargetTitle); // returns true if any of a todo in the array has the same title
}

function createTodoObject(title) {
  return { title };
}

function displayTodo(todo) {
  const todoElement = createTodoElement(todo);
  appendElementToBody(todoElement);
}

function createTodoElement(todo) {
  const todoElement = document.createElement('div');
  todoElement.id = todo.title;
  todoElement.textContent = todo.title;
  return todoElement;
}

function appendElementToBody(element) {
  document.body.append(element);
}

const todoForm = document.querySelector('#todo-form')
todoForm.addEventListener('submit', handleNewTodoSubmit);

In this example code, every function, including appendElementToBody, does what you expect 100% of the time.

The validation of the todo was moved from appendElementToBody to handleNewTodoSubmit. This is a much more appropriate place for it.

The correct way to think about it is that the todo should not be created if it already exists. That's the domain of the handleNewTodoSubmit function, not of the appendElementToBody function.

In other words, the check is now at a place where you would expect it to be. This means that debugging will be easier if there is a problem, because you'll find the relevant code faster.

Example: doubleSpeed

Code for the good version of doubleSpeed:

function doubleSpeed(gameObject) {
  gameObject.speed = gameObject.speed * 2;
}

Code for the bad version of doubleSpeed:

let shouldDouble = true;
function doubleSpeed(gameObject) {
  if (shouldDouble) {
    const currentSpeed = gameObject.speed;
    gameObject.speed = currentSpeed * 2;
  })
}

This example is the same as the appendElementToBody example.

doubleSpeed should do what it says on the tin. It shouldn't have implicit conditions where it does what you expect sometimes and nothing at other times. That's unexpected and can only lead to trouble.

Instead, some code higher up should decide if it needs to call it in the first place. Then it can either call it or not call it.

The benefits of the good version of the code are that it's:

predictable, easy to track and less likely to have weird bugs that depend on weird state and time
easy to understand
reusable. You can reuse this function anywhere in the codebase. However, you can't reuse the bad version unless you need the exact same condition.
easy to test. The bad version is practically impossible to test (because your test file can't modify the variable shouldDouble, unless you do a lot of work to circumvent that).

Example: incrementSpeed

This example showcases why you should avoid having Boolean parameters.

Here is the good version of the code:

function incrementSpeedDamaged(gameObject) {
  gameObject.speed = gameObject.speed + 0.5;
}
function incrementSpeed(gameObject) {
  gameObject.speed = gameObject.speed + 1;
}

Here is the bad version of the code:

function incrementSpeed(gameObject, isDamaged) {
  if (isDamaged) {
    gameObject.speed += 1;
  } else {
    gameObject.speed += 0.5;
  }
}

Does the Boolean parameter matter?

Yes, it does. Not a tremendous amount in this example, but it's definitely worse.

One problem with Boolean parameters is that they multiply the number of code paths in the function. In other words, there is an if / else statement in there.

For example:

function (booleanParameter) {
  if (booleanParameter) {
    doSomething();
  } else {
    doSomethingElse();
  }
}

Every additional Boolean parameter can double the number of possible code paths.

For example, with two Boolean parameters, this is what the code may look like. Pay particular attention to the sendData function:

function sendData(data, isValid, isDataFormatted) {
  if (isDataValid) {
    if (!isDataFormatted) {
      data = formatData(data);
    }
    fetch('https://myfakeapi.com', {method: 'POST', body: JSON.stringify(data)})
  } else {
    if (!isDataFormatted) {
      data = formatInvalidData(data);
    }
    fetch('https://myfakeapi.com/errors', {method: 'POST', body: JSON.stringify(data)})
  }
}

function formatData(data) {
  return data.split('');
}

function formatInvalidData(data) {
  return 'Error: ' + data;
}

function main() {
  const data = '123'; // get data from somewhere
  const isDataValid = validateData(data);
  const isDataFormatted = false;
  sendData(data, isDataValid, isDataFormatted);
}

The sendData function is quite complicated. It's difficult to understand and read through it. It has nested conditionals, which make code harder to understand and work with.

It's also not reusable, unless you need those exact conditions and arguments elsewhere. In particular, if you need if more conditions tomorrow, you'll need to add even more code to sendData to handle them. This means that sendData may grow over time, and become even more complicated.

It's also difficult to test. You need tests covering each possible code path.

In short, it's difficult to work with and it can become even more complicated in the future.

The better version is to have simple unit functions, that only do one thing, without conditionals. For example:

function sendData(data) {
  fetch('https://myfakeapi.com', {method: 'POST', body: JSON.stringify(data)});
}
function reportDataError(data) {
  fetch('https://myfakeapi.com/errors', {method: 'POST', body: JSON.stringify(data)});
}
function formatData(data) {
  return data.split('');
}
function formatIvalidData(data) {
  return 'Error: ' + data;
}
function main() {
  const data = '123'; // get data from somewhere
  const isDataValid = validateData(data);
  if (isDataValid) {
    const formattedData = formatData(data);
    sendData(formattedData);
  } else {
    const formattedData = formatInvalidData(data);
    reportDataError(formattedData);
  }
}

Notice that the sendData function is now trivially simple.

You may be thinking "but those conditions just moved to the main function, isn't that the same thing?" That's a fair argument. However, this code still has some advantages. In this version:

the unit functions are simple and easy to understand
the unit functions are reusable all over the codebase. If you need to handle new conditions, you can handle them in a different high-level function like main and still reuse the small unit functions.
the unit functions are trivial to test
the program in general is easier to modify or extend if you need more functionality

A more important reason is how the good version of the code can grow tomorrow, versus the bad version of the code.

For example, if new conditions arise tomorrow, the good version of the code may end up like this:

// We've kept the unit functions like sendData, but they're omitted for brevity

// More simple functions for new use-cases
function validateDataADifferentWay(data) {}
function validateSpecialData(data) {}

function main1() {
  const data = '123'; // get data from somewhere
  const isDataValid = validateData(data);
  if (isDataValid) {
    const formattedData = formatData(data);
    sendData(formattedData);
  } else {
    const formattedData = formatInvalidData(data);
    reportDataError(formattedData);
  }
}

function main2() {
  const data = '123'; // get data from somewhere, it should always be valid
  const speciallyFormattedData = formatDataADifferentWay(data);
  sendData(speciallyFormattedData);
}

function main3() {
  const data = '123'; // get data from somewhere
  const isDataValid = validateSpecialData(data);
  if (isDataValid) {
    const formattedData = formatData(data);
  } else {
    const formattedData = formatInvalidData(data);
    reportDataError(formattedData);
  }
}

This is quite good.

The unit functions we had are still 100% the same. We handle the new conditions in the different main functions which aren't too complicated. For new, specific functionality, we've created the new unit functions validateSpecialData and formatDataADifferentWay. (We've omitted the implementations for brevity.)

However, the bad version of the code wouldn't fare so well. Every new condition would be handled in sendData. As a result, sendData would become much more complicated.

Consider this example where we add a Boolean parameter needsSpecialFormatting. It's a flag which says that we should format the data in a different way:

function sendData(data, isValid, isDataFormatted, needsSpecialFormatting) {
  if (isValid) {
    if (!isDataFormatted) {
      if (needsSpecialFormatting) {
        data = formatDataADifferentWay(data);
      } else {
        data = formatData(data);
      }
    }
    fetch('https://myfakeapi.com', {method: 'POST', body: JSON.stringify(data)})
  } else {
    if (!isDataFormatted) {
      if (needsSpecialFormatting) {
        formattedData = formatDataADifferentWay(data);
      } else {
        formattedData = formatInvalidData(data);
      }
    }
    fetch('https://myfakeapi.com/errors', {method: 'POST', body: JSON.stringify(data)})
  }
}

function main1() {
  const data = '123'; // get data from somewhere
  const isDataValid = validateData(data);
  const isDataFormatted = false;
  sendData(data, isDataValid, isDataFormatted, false);
}

function main2() {
  const data = '123'; // get data from somewhere, it will always be valid
  const speciallyFormattedData = formatDataADifferentWay(data);
  sendData(data, true, false, true);
}

function main3() {
  const data = '123'; // get data from somewhere
  const isDataValid = validateSpecialData(data);
  if (isDataValid) {
    sendData(data, true, false, false);
  } else {
    sendData(data, false, false, false);
  }
}

As you can see, with one more Boolean parameter, sendData is becoming much more complicated. Things would become even worse as more parameters are added.

On top of that, even the call for sendData(data, true, false, false) is difficult to look at. It's a mental exercise trying to match each Boolean to the parameter it represents. It's possible to improve this by making sendData accept an object instead, but it's still more effort than the simple version.

In addition, what sendData does may be unexpected at first glance by a programmer who's not familiar with the code. As mentioned earlier, a programmer would expect that function to send some data and call it a day, not to do anything else. After all, the function's name is sendData, not send_data_if_valid_otherwise_report_error_and_also_format_the_data_if_needed (used underscore case to make it easier to read).

Finally, this function is breaking many of the programming principles, because:

it does many things, which breaks separation of concerns / single responsibility principle
it's not simple, which breaks KISS
it has many conditions with logic coupled together, which makes it more error prone to change. This breaks the goal of programming principles themselves, which is that code should be easy to work with.
it's not reusable for different conditions unless you add even more logic. This breaks the open-closed principle.

So instead, prefer small unit functions that only do one thing. If you have to pass a Boolean to a function, consider splitting it into two functions instead. One will handle the true case and the other will handle the false case.

Linking back to programming principles

The main thing to keep in mind is that these guidelines are just applications of the core programming principles. That includes KISS, the principle of least astonishment, separation of concerns / single responsibility principle and handling side effects well.

All of those principles point towards functions that tend to be small, only do one thing, are reusable, easy to understand, easy to change and easy to test.

Additionally, someone who understands those principles well would naturally create code units like the ones described in this article.

So the point of this article isn't necessarily to be prescriptive about how to create small units. Instead, think of it as an example for how to apply those principles in this situation.

In other words, it's a specific use-case to help you become more familiar with these principles in general. That way, you can apply them everywhere, without having to learn how to handle an infinite number of individual use-cases like this one.

So, to write even better code, I recommend looking at the programming principles more closely. To do that, you can have a look at clean code and programming principles - the ultimate beginner's guide, which is a crash course on some fundamental programming principles.

Applying these guidelines to other code units

We examined functions at the edge of an application because those can afford to be simple. Other functions may be more complicated.

As shown in the examples, higher-level functions can have conditionals and they can be longer.

As nice as it would be to avoid conditionals altogether, that's just not possible.

Every real program needs to do different stuff under different circumstances. The very best case is to format your conditionals differently and to put them in a more appropriate place, so that they're easy to work with.

Also, it's not possible for all of your functions to truly only do one small thing. The only functions with that luxury tend to be the functions at the very edge of your application. For everything else, it's more likely that they'll do a few things, say, 3 things, at an appropriate level of abstraction, in a way that it can be described as one thing.

For example:

function handleFormSubmit(event) {
  event.preventDefault(); // necessary to handle form submission with JavaScript, rather than HTML
  const data = getDataFromForm();
  const formattedData = formatData(data);
  sendData(formattedData);
}

The handleFormSubmit function does 4 things. It has 4 lines of code after all. However, you can also think of it as doing one thing. "It handles the form submission", that's one thing. Both are correct, it depends on what level of abstraction you consider.

So, since you can't just avoid conditionals and since your functions can't just do one thing, what can you do? All you can do is apply programming principles. A.k.a. do anything you can to ensure that your code is correct and easy to change.

At any given time, consider if your code is:

easy to understand
easy to reuse
easy to change
easy to test

Be pragmatic

As always, remember to be pragmatic. In this article, we examined how to write and structure good code units at the edge of your application.

That's the ideal, but the ideal might not always be realistic. If you can write code units like this without much effort, then do it. But if that's not possible, well, don't postpone a critical feature by 1 month because you want to refactor every code unit in your codebase. That wouldn't make sense or be realistic.

Instead, do the best you can and be pragmatic. You probably need to balance good code (which makes future development easier) and releasing features in an appropriate timeframe for your work.

Final notes

That's it for this article.

I hope you found it useful and I hope that the concepts and the reasons for them made sense.

What are your opinions on how code units should be, particularly units at the "edge" of your application? Is there anything you disagree with? Anything that wasn't covered? If there is anything, please leave a comment below.

Otherwise, for more details on how to write clean code and apply programming principles, please check out clean code and programming principles - the ultimate beginner's guide.

How to make accessible websites - The ultimate guide

Spyros Argalias — Wed, 17 Feb 2021 10:59:38 +0000

For everything you need to know about accessibility, check out Web accessibility - Everything you need to know, on Programming Duck.

Disclaimer: I'm not a lawyer. This article only represents my personal opinion and current understanding. It is not legal advice. Please consult a lawyer for information on the legal aspects of accessibility.

Ensuring that your website is accessible shouldn't be difficult. A little bit of effort can take you a long way in your day-to-day work.

To start with, if you're completely new to accessibility, learning some of the basics will be very helpful. Please see how to learn accessibility for some useful resources to start with.

Afterwards, here is a simple process you can use to apply accessibility as you work:

Learn about your legal accessibility requirements
Use semantic HTML
Check accessibility checklists frequently to ensure you've applied accessibility correctly in your work
Test your website's accessibility to ensure you're doing it correctly

Optionally, you can also:

Make accessibility part of the standards and the development process
Educate people about accessibility
Hire specialists if you need more help

Here are more details on each part of the process.

Legal requirements

Before starting, you should know about your legal requirements.

In general, for most companies, you should meet the WCAG 2.1 (or more likely, the latest published version) level AA accessibility standards. Level A is probably not sufficient. Level AA is the standard. Level AAA is "aspirational". It's generally not a legal requirement to meet it, however it's great if you can.

Additionally, you may need an accessibility statement depending on your country's laws. Even if you don't, WCAG mentions that there are many good reasons to have one. For information on accessibility statements, please see the WCAG article on developing an accessibility statement.

Use semantic HTML

Using semantic HTML is the most important thing you can do for accessibility. An easy way to do this is to scan through the HTML element reference on MDN. It lists all of the HTML elements and says what they should be used for. You can also visit a dedicated page for every element for much more information about it.

Use useful checklists

As you work, keep referring to these useful checklists:

WebAIM WCAG checklist

The WebAIM WCAG checklist provides great recommendations on the most important things you can do for accessibility. It's one of the simpler checklists in this section. As a result, it's great to refer to frequently and for the majority of your work.

WAI-ARIA authoring practices

The WAI-ARIA authoring practices provide guidelines for custom widgets created with JavaScript (things like accordions, custom dropdowns, etc.). Following these guidelines is very important for the accessibility of these widgets. Therefore, I recommend always referring to this resource whenever you're working on something like that.

Additionally, this resource provides guidance on naming for particular elements. Some elements require a name, while for others a name is recommended, but not required. Thankfully, if you use semantic HTLM, the majority (if not all) of the elements that require a name will automatically get one associated to them from their content. In other words, you shouldn't need to check this section very often.

However, the naming section provides additional recommendations for naming elements. If you want to improve the experience of screen reader users even further, feel free to check this section once in a while and apply some of its recommendations.

WCAG

WCAG includes the official specification that's mentioned in the legal requirements. To be 100% compliant, you have to check against that.

However, this resource seems more difficult to work from than the others. For this reason, you may find it easier to work from the WebAIM resource in your day-to-day work. Then, you can check this resource when you want to do a more comprehensive accessibility audit.

Frequency of using the checklists

As for the frequency of using these checklists, you have different options. You can:

Refer to them every time you're working on something relevant and want additional information
Scan over the documents every once in a while, perhaps once a week or so. That way, you can recall the work you did that week and make sure that you haven't missed any accessibility requirements.

Test

To really be sure that your website is accessible, you need to test it.

There are different kinds of accessibility tests that you can do. They vary in complexity and time required. They can also be manual or automated.

Manual tests

Here are some things that you should consider testing manually.

Zoom

Test how your website looks when you use browser zoom. The WCAG standard currently requires your page to be readable and functional at 200% zoom. However, feel free to test higher than that.

Consider also testing your website with OS-level zoom (a zoom setting applied in your operating system settings).

Consider also testing your website with an application such as ZoomText.

Screen readers

Test your website with a screen reader.

For more thorough testing, consider testing your website with different common combinations of operating systems, screen readers and browsers:

Mac or iOS with Voiceover and Safari
Windows with Jaws or NVDA
ChromeOS with ChromeVox and Chrome
Android with accessibility options enabled and Chrome
Linux with Orca

Keyboard navigation and interactivity

Test the keyboard navigation and interactivity of your website. Pay particular attention to things that work with JavaScript, such as custom widgets, modals, etc.

Ensure that keyboard navigation is sensible, easy and clear. The user should know exactly where the focus is every time.

Also ensure that the entire website can be operated using just the keyboard. The only exception to this rule is if that's practically impossible, for example if you have functionality for free-hand drawing.

Vision deficiencies

Some browsers have a vision deficiency simulator. If you're using Chrome, here's Andy Osmani's tutorial on the vision deficiencies simulator in Chrome. Here's an article for using color vision simulator in Firefox.

Alternatively you can use a browser extension like NoCoffee vision simulator.

Document outline

The document outline refers to the headings of a webpage. Specifically, it refers to their heading level and their order.

Heading levels should descend in order, without jumps.

For example, this is fine:

<h1>h1</h1>
<h2>h2</h2>
<h2>h2</h2>
<h3>h3</h3>

However, the following is not fine, because it skips / jumps from an h2 to an h4:

<h1>h1</h1>
<h2>h2</h2>
<h4>h4</h4>
<h2>h2</h4>

An easy way to test these is to install a browser extension like WAVE or Outliner. They can show you the document outline very clearly, without you having to look at the source code of the page.

Accessibility testing tools

Here are some tools that you can consider using for accessibility testing.

Third-party services / analysers:

Tenon

Page testing tools:

Chrome developer tools:
- Accessibility tab
- Rendering tab -> Vision deficiencies simulator
- Lighthouse
Browser extensions:
- WAVE
- Outliner
- Axe
- Tota11y

Build tools:

Also consider accessibility code linters for the technologies you work with. One example is the eslint-plugin-jsx-a11y for JSX.

Unit, integration and end-to-end tests for accessibility

In rare cases, you may want to write unit, integration or end-to-end tests for accessibility.

For example, consider that you've created a custom widget. You may want to have an end-to-end test for it to make sure that the widget can receive focus when the user presses TAB on their keyboard.

Recommendations for getting started with accessibility testing

When it comes to accessibility testing, there are many things you could test and many tools you could use.

To keep things simple, consider starting with the following:

Use lighthouse to run audits on pages on your website. Then fix any errors it mentions.
Do some manual testing for keyboard navigation, screen readers, the document outline and zoom.

As you get more comfortable, you can try out additional tools. For example:

Try installing the WAVE browser extension or an alternative.
Try setting up some automated accessibility testing with Lighthouse, axe-core or an alternative.
Try installing some relevant code linters, such as eslint-plugin-jsx-a11y.
And so on.

Alternatively, if you have the budget, you can also use a service like Tenon or even hire an accessibility consultant.

Make accessibility a standard and part of the development process

It's useful to make accessibility an official part of your standards and development process. That way, it won't be neglected.

This is similar to how you would make anything a standard in your codebase.

You may declare in your standards documents that accessibility is important and that all work is expected to meet the WCAG 2.1 AA specification, or at least the WebAIM recommendations and ARIA authoring practices recommendations.

You could also make it part of your development process:

You could set up automated accessibility tests to be run on the pull request for every story.
You could require developers to test the accessibility of their work before they submit a new feature.
You could run a small accessibility audit once a month, or maybe a comprehensive audit once a year.
And so on.

Educate people whose work ends up on the front end

As explained in Accessibility - Everything you need to know, front end developers need to know more about accessibility than anyone else.

However, all work that ends up on the front end can affect accessibility. This includes work done by designers, content creators and other job roles. Therefore, it's useful for them to know about accessibility too.

For this reason, it may be good for front end developers to educate them.

Additionally, developers can collaborate with them or advise them on creating standards that ensures their work is accessible. For example, they may advise copywriters (people who write text on the website) that their work needs to follow a reasonable document outline.

Hire third-party accessibility consultants

Even if the developers in the company know about accessibility, they're not specialists. They could be missing things that only a specialist may know of. Even if they're not missing any legal requirements, a specialist may be able to enhance accessibility in ways that the developers may not think of.

So, if you want to be extremely thorough with accessibility, you may have to hire a third-party accessibility consultant or a specialist.

Summary

Accessibility work doesn't have to be difficult.

Here is a simple process you can use:

Learn about your legal accessibility requirements
Use semantic HTML
Check accessibility checklists frequently to ensure you've applied accessibility correctly in your work
Test your website's accessibility to ensure you're doing it correctly

Optionally, you can also:

Make accessibility part of the standards and the development process
Educate and advise people on accessibility
Hire specialists if you need more help

Final notes

That's it for this article.

Please leave a comment if you have any feedback, anything I missed that might help others, or even anything you disagree with.

Next, if you want to know more about accessibility, please see the article Web accessibility - Everything you need to know.