Category: WTF is

I recently tried an online program called Launch School, which focuses on improving students’ Software Engineering competence via something called ‘Mastery Based Learning’.

Although I have decided not to continue with Launch School, I would definitely recommend it to people looking to move into Software Engineering from another background.

I learnt quite a bit during the two months I spent on the program, but could not justify the time commitment required.

I did, however really like the concept of ‘Mastery’ and have continued to use this approach to improve my Maths skills in my spare time.

“Mastery learning maintains that students must achieve a level of mastery (e.g., 90% on a knowledge test) in prerequisite knowledge before moving forward to learn subsequent information.”

This short book explains the concept more fully, and is worth a read if you want to learn more.

Mastery learning means getting to a point where you know any required foundational topics to an insane degree, before moving up to the next level of complexity.

Mastery based learning works especially well when applied to subjects that require a student to sequentially build on previous knowledge, to gain a progressively more complex understanding about something.

Good examples of subjects like this are Maths, Science, and Engineering.

These, coincidentally are the subjects I sucked at most at school!

Typically, after the first couple of weeks in a new term, I failed to understand something crucial, got annoyed and glossed over it because it was boring to learn and made me feel stupid, and moved onto the next piece of work, which then made even less sense.

Unsurprisingly this did not result in huge amounts of academic success and led to the (I now think false) belief that I ‘wasn’t a maths person’.

I have been working gradually through this book, and by far the most important thing I’ve learnt so far, is that it is healthy and necessary to embrace the suck.

By that I mean, if you are really learning, it will be hard.

Mastery based learning means spending almost all of your time on material you are bad at, and trusting that through consistent effort and practice, you will improve.

In order to improve, you must get used to this feeling of being stupid and clumsy, and embrace it.

After a few months of this approach, I’ve found that I genuinely enjoy the feeling of fumbling around in a new topic, safe in the knowledge that if I continue to fumble, and ‘deliberately practice’, it will eventually make sense.

I’d be very interested to hear anyone else’s thoughts or experiences in this area, especially any teachers, as I really believe that this approach would have worked much better for me at school.

I spent a bit of time at work thinking about the carbon cost of the internet.

Here are my rambling thoughts on the matter in slide format.

(DISCLAIMER: Some facts in this are suspect and all are stolen from better people than me, but I think the general conclusions, or lack thereof probably hold true…)

A dependency can be thought of as anything your code depends on in order to work.

As an example, say we have a class like below:

import { dependency } from 'dependency-library';

class ExampleClass = {

  public doSomething() {
    dependency.doSomething();
  }

}

We can say that ExampleClass depends on dependency-library, or dependency-library is a dependency of ExampleClass.

In this example we could say that ExampleClass is tightly coupled to dependency-library.

Any time we create a new ExampleClass(), we will also directly pull in dependency-library.

If for some reason we don’t want these two to be directly coupled, we could use dependency injection:

Dependency injection version:

class ExampleClass = {

  constructor(private dependency: DependencyLibrary) {}

  public doSomething() {
    this.dependency.doSomething();
  }

}

const instantiatedExampleClass = 
  new ExampleClass(new DependencyLibrary());

Why bother?

• Generally decoupled code is easier to modify and less fragile.
• It makes unit testing very simple as spying on injected dependencies and passing in simpler implementations is easy.
• It can allow for highly configurable code where different implementations that use the same public interface can be subbed in where needed.

What is Nrwl nx?

An opinionated set of tooling written by some clever people to help with writing enterprise level Angular applications.

It involves working within a monorepo, or ‘workspace’ as they refer to it, which has multiple apps in it, and extracting functionality out into reusable libraries to improve code reusability and decoupling.

You should seriously check it out:

https://nrwl.io/nx

Why should I care?

My team has a need to support development of a front end layer for a white label product, with multiple, localized, themed, customisable instances of the product to be sold to different clients.

A typical Angular feature architecture does not optimally support this requirement.

We need to minimise code duplication, yet retain the ability to support apps with different functionality and theming.

We took the decision to use a workflow whereby almost all code is extracted into reusable libs inside a monorepo.

Our apps then become nothing more than configuration: a place to assemble the libs and theming information needed to personalise and customise the application for a specific client.

This allows for massively faster development on a per-client basis, and any new functionality can be shared among all client apps, meaning we are continually improving our core product, while supporting multiple applications.

We are using Nrwl nx tooling to achieve this and so far it has been extremely nice to work with.

What is a monorepo and why use one?

There is some disagreement about the merits of monorepos, and many other people can explain the nuances better than me. It is worth Googling if you are new to the concept. Here are some starting points:

https://danluu.com/monorepo/ https://medium.com/@maoberlehner/monorepos-in-the-wild-33c6eb246cb9

However, on a basic level we took the decision to use a monorepo because:

• It supports a CI/CD pipeline. All code has to go through the same set of automated tests before it is merged.
• We can ensure code standards are clear and enforcable by putting all code through the same linting and formatting rules.
• Code is easily shareable between applications.

What are libs?

Nrwl nx introduces the concept of libs. These are standalone, decoupled pieces of functionality for an Angular application. They can be thought of as the building blocks that we use to create our applications.

There are a number of different types of lib that we have defined, and put in separate directories, to make it easier for developers to know where to put a particular piece of code:

• features – a standard Angular feature module. It may be composed of other features. It may have services, state management, routing, container/smart components and dumb/presentational components.

• api – an Angular module with a service for calling a REST endpoint associated with a specific resource. For example a ‘cars’ api module would handle all http verbs associated with cars (‘Get’, ‘Put’ etc.). These are deliberately granular and are imported by feature modules for making api calls.

• components – any shared dumb components that don’t belong in a feature module. These should not interact with a sandbox(see ‘what is a sandbox?’), and should be purely presentational.

• utils – any heavy lifting code that isn’t already in a feature level service. This is pure business logic and should not deal with rendering.

• core – functionality that every application needs. For example top level error handling.

• scss – sass utilities. For example mixins, variables etc.

What are apps?

Apps are just Angular applications. However they are very slim. They shouldn’t have any more in them than the following:

• Top level lazy loaded routing.
• Custom theming information (fonts, color palette, icons etc.).
• Assets.
• App specific environment variables.
• E2E tests.

Everything else should be in a standalone lib somewhere.

Feature level architecture

Of the libs folders, the features one is probably the most complex.

As an example, a user-registration feature might look like below (NB spec files have been excluded for clarity but all files with logic in them will have an equivalent spec file):

/libs
  /features
    /user-registration
      /src
        + +state
          - ...
        + containers
          - ...
        + components
          - ...
        + models
          - ...
        + services
          - ...
        - user-registration.module.ts
        - user-registration.sandbox.ts
      - index.ts

Here are the interesting bits in order:

• +state folder is filled with ngrx redux stuff (actions, reducers, effects).

• containers folder is filled with ‘container’ or ‘smart’ components. These are components that interact with the sandbox (don’t worry, sandbox will be explained below… ).

• components folder is filled with ‘dumb’ or ‘presentational’ components. These simply have data flowed into and out of them. They don’t know about anything else, hence they are dumb.

• models folder is filled with typescript interfaces describing any data types associated with the feature module.

• services folder is filled with services. Any pure business logic associated with the feature should live in a service here.

• user-registration.sandbox.ts is a sandbox.

What is a sandbox?

Good question.

In the most basic terms, it is an abstraction layer between smart container components and state.

It allows our smart container components to deal with a clean and descriptive interface, rather than talking directly to redux.

It exposes methods for updating state, and streams of data for flowing state out of the sandbox.

The thinking is that smart components don’t really care that their data is coming from an ngrx store, so perhaps they shouldn’t know.

The reason it is called a sandbox is that we stole the name and the concept from here:

https://blog.strongbrew.io/A-scalable-angular2-architecture/ https://blog.strongbrew.io/A-scalable-angular-architecture-part2/

We have tweaked the original concept slightly, in that we still make any http calls via effects, but other than that it is pretty similar.

The name ‘sandbox’ apparently is used because in a sandbox, you can only play with the toys you are allowed access to.

Here is an example to hopefully make the concept clearer:

user-registration.sandbox.ts:

import { Injectable } from '@angular/core';
import { select, Store } from '@ngrx/store';
import { Observable } from 'rxjs/Observable';

import { SecurityQuestion } from '@ten-platform-app/api/api-security-questions';

import { UserRegistrationStateMap, getSecurityQuestions } from './+state';
import { LoadSecurityQuestionsAction } from './+state/security-questions.actions';

@Injectable()
export class UserRegistrationSandbox {
  // A publicly exposed stream of security questions that can be hooked into by a smart component.
  public securityQuestions: Observable<SecurityQuestion[]> = this.store.pipe(
    select(getSecurityQuestions),
  );

  // The sandbox has our feature level redux store passed into it.
  constructor(private store: Store<UserRegistrationState>) {}

  // Our smart component uses this method to request security questions, and subscribes to the public stream above.
  public getSecurityQuestions() {
    this.store.dispatch(new LoadSecurityQuestionsAction());
  }
}

How do we structure our state management code?

We use the redux pattern to handle state in our libs:

https://redux.js.org/introduction.

We use the ngrx implementation of redux:

https://github.com/ngrx

This is what the +state folder looks like for a typical module:

  /+state
    - user.actions.ts
    - user.actions.spec.ts
    - user.effects.ts
    - user.effects.spec.ts
    - user.reducer.ts
    - user.reducer.spec.ts

There are three types of file, actions, effects and reducer.

In our project these files are generated using custom angular schematics.

These schematics work the same way the angular cli does, and will generate a basic store that works. This cuts down on boilerplate code and helps us to standardise how we write our state management code.

Actions and reducers are very much like any other redux implementation, with the slight difference that everything is strongly typed, using Typescript.

Effects

Effects are used to handle asynchronous code. For example, any http call will be done inside an effect.

Our effects have some specific bits of code in them that allow them to work with our sandbox layer and should be explained:

import { Injectable } from '@angular/core';
import { Effect, Actions } from '@ngrx/effects';
import { DataPersistence } from '@nrwl/nx';
import { of } from 'rxjs/observable/of';
import { map } from 'rxjs/operators';

import { ApiSecurityQuestionsService } from '@ten-platform-app/api/api-security-questions';

import { UserRegistrationFeatureStore } from './index';
import {
  LoadSecurityQuestionsAction,
  LoadSecurityQuestionsFailureAction,
  LoadSecurityQuestionsSuccessAction,
  SecurityQuestionsActionTypes,
} from './security-questions.actions';

@Injectable()
export class SecurityQuestionsEffects {
  @Effect()
  public loadSecurityQuestions = this.dataPersistence.fetch<
    LoadSecurityQuestionsAction
  >(SecurityQuestionsActionTypes.LOAD_SECURITY_QUESTIONS, {
    run: (
      action: LoadSecurityQuestionsAction,
      state: UserRegistrationFeatureStore,
    ) => {
      // check state for existing security questions.
      // Only make call to get them from the apiService if needed.
      if (state.userRegistration.securityQuestions.loaded) {
        return of(
          new LoadSecurityQuestionsSuccessAction({
            questions: state.userRegistration.securityQuestions.data,
          }),
        );
      } else {
        // Delegate the api call to the relevant service.
        return this.apiService.getSecurityQuestions().pipe(
          map(questions => {
            return new LoadSecurityQuestionsSuccessAction({
              questions: questions,
            });
          }),
        );
      }
    },

    onError: (action: LoadSecurityQuestionsAction, error: any) => {
      return new LoadSecurityQuestionsFailureAction({ error });
    },
  });

  constructor(
    private actions: Actions,
    // This is a utility provided by Nrwl/nx.
    // It has convenience methods that eliminate race conditions
    // and ensure consistency when fetching data
    private dataPersistence: DataPersistence<UserRegistrationFeatureStore>,
    // A granular api service is imported for actually making REST calls.
    // This follows the principle of single responsibility.
    private apiService: ApiSecurityQuestionsService,
  ) {}
}

Note that the effects class does not directly interact with the httpClient. This is delegated to a granular api service, which handles the api call and any data transformation before returning a stream of appropriately typed data.

Effects work by watching a global stream of actions.

If an action of the right type is seen (in the example above a LOAD_SECURITY_QUESTIONS action), then some piece of asynchronous code is run.

Once that code has finished, a new stream is returned, with a new action.

So basically effects just map action streams to other action streams, and do a bit of work in the middle.

Redux alone is not able to smoothly handle asynchronous code, so these side effects are handled inside effects.

In addition, effects are where we handle optimistic and pessimistic updates and caching of data.

Again, Nrwl nx provides convenience methods for optimistic and pessimistic updates:

https://nrwl.io/nx/guide-data-persistence

Conclusion

Architecting Angular applications in a way that allows multiple developers to work efficiently together with minimal friction is a tough job.

This is my team’s attempt to solve some of those problems. Hopefully it may help other teams too!

Tech debt, or technical debt is pretty much exactly what it sounds like.

When building software, there is a constant trade off between implementing features quickly, and implementing them right.

Ideally, you would always build them right, and in the long term this will also be the quicker route.

When features are implemented with care they are tested and reliable, flexible and well architected. Future developers working on the code will probably not have a lot of trouble understanding the work, and will be able to build on it and modify it with ease.

However, there is an upfront time cost to doing things the right way, and sometimes it can be worth taking on short term ‘tech debt’ in order to get a feature out in time for a specific deadline.

This means that the implementation may cut some corners, and be designed in a less flexible way. Testing coverage may be lower, and the architecture will be less thoroughly planned out.

This ‘debt’ in a healthy system will be paid off as soon as possible after the immediate deadline.

If it is not paid off, and more technical debt is taken on, then the product can begin to suffer.

Changes become harder as poorly architected code, often tightly coupled to other areas of the system, introduces bugs. Fixing these bugs can cause other bugs, and little by little it becomes impossible to add new features, or to amend existing features to match changing business requirements. The development team finds that most of their time is taken up fire fighting bugs, and the product growth grinds to a a halt.

This is a bad situation.

The solution is to only take on tech debt when absolutely necessary, and to pay it off as soon as possible, via constant diligent refactoring of the code base.

An analogy I like is that coding is in many ways like gardening. The job of a developer is to grow and modify various features, such that a product can adapt to meet the changing needs of its users.

Like gardening, there are many factors that affect the ecosystem that the features are growing in, and they must be constantly monitored in order for the product to grow in a healthy and sustainable way.

Technical debt can be thought of as the soil quality. If too many wacky things are done to the soil, it will lose its nutrients, and be unable to support the growth that is needed. If this goes on for too long, it will be unable to support any growth, and the garden will die. Conversely, if the soil is well cared for and ordered, the garden can flourish, and support a far greater amount of growth and change.

Being a good developer is about being a professional, and often this will mean saying no to taking on technical debt. Normally you will be under pressure from managers and clients to turn things around to tight deadlines. Agreeing to cut corners in order to meet these deadlines should be done very sparingly. Another good analogy, courtesy of Uncle Bob is the case of doctors and hand washing.

If a patient or a manager told a surgeon to skip washing their hands, because it was taking too long, and using too much water etc., the doctor would refuse. This is because the doctor is a professional, knows their craft, and knows the cost of not washing their hands.

Likewise, if a developer is a professional, and knows the true cost of incurring tech debt, then they have an obligation to refuse to take it on unnecessarily, even if that means saying no to a manager, or a client.

A class is a construct found in Object Oriented Programming. It is a way of grouping data, and the methods for interacting with that data in one place. It also exposes a public interface that can be used by other code to interact with the class.

Classes have to be instantiated. That is to say, at some point if you’ve defined a lovely class MyLovelyClass, in order to use it you will have to make a call to new MyLovelyClass().

To repeat what every guide to classes I’ve ever read says: Classes can be thought of as blueprints for how to make something.

It will often but not always model a real world object. To make this clearer let’s take a look at an example, using TypeScript:

class Bag {

    constructor() {
        this.contents = [];
    }

    private contents: String[];

}

Here we’ve modelled a bag, which can have things in it, in the form of an array of strings. It’s a bit useless at the moment as we can’t actually put anything in it, because the contents array is private, so can’t be accessed from outside the class. To clarify:

const bag = new Bag();

bag.contents.push('sweet-coding-book');

This will not work, as bag.contents is not available to us. One solution would be to set the contents array to public:

public contents: String[]

But this would be a bad thing for a number of reasons. Firstly, if at any point we decide we want contents to be a different data type. For example lets say we decide to store our items in a dictionary instead:

public contents: { [key: string]: string; };

Now, if we have existing code that does something like below:

const bag = new Bag();

bag.contents.push('sweet-coding-book');

It will need to be changed. This example is trivial, but in a big project, this could take a long time to refactor.

Alternatively, if we did something like below, we can change our implementation of storing things in the bag, and any existing code will still work:

class Bag {

    constructor() {
        this.contents = {};
    }

    private contents: { [key: string]: string; };

    public addItem(item: String) {
        this.contents[item] = item;
    }

}

const bag = new Bag();

bag.addItem('super-sweet-coding-book');

This is a pretty contrived example, but things similar to this happen all the time when coding.

So there is a very simple example of a class, which hopefully gives a basic understanding of what a class is, and a few of the benefits it offers.