Home on Sam Atkins

New Tooling in 2025

Wed, 12 Nov 2025 06:37:40 +0000

I read a blog about the tools someone uses and this prompted the idea to write what I use. OK, I’m shamelessly copying the idea of writing about the tools I use day to day. (I can’t remember where I saw it but if I find it, I will add a link to it here.)

After several years of using the same old tools day in and day out, what surprised me this year is not just the new tools I use but how my typical day writing code has changed. AI coding agents getting good is the reason for this.

Enough of an intro, here are the tools I use at work for software development.

Claude Code

Let’s start with a tool which has fundamentally changed how I work and the tools I now use.

Claude Code is an AI tool that for me lives up to the hype. It isn’t perfect but I consider it an invaluable tool that I use everyday in my job. Claude works away in the background until I’m notified (via a hook) that requires my input. I review and may edit the diff in my IDE and either continue coding from there or go back with another prompt to let Claude continue.

Ghostty

I liked iTerm. I liked the idea of Warp but wanted more granular control over settings, config and so on.

Ghostty is a super fast terminal, with zero config required… but if you do want to configure it (like I did), it can be done in a config file. Perfect for adding to however you manage dotfiles and configuration.

I can add things like atuin for shell history and Fish shell for 90s goodness. I held off switching to Fish for so long, I was so invested in my bash dotfiles and aliases etc. But so glad I made the switch, so much easier to work with.

Zellij

For those missing features in Ghostty (like search), then Zellij is the perfect companion. An easier onboarding experience than tmux. I’m super happy with Zellij. I have custom layouts for my dev work, with split panes with e.g. Lazydocker or Claude Code autoloaded.

jj

I’ve been using Jujutsu Version Control System aka jj since the start of the year and I love it. No more trying to work out arcane git magic. A simple, consistent UI, yet just as powerful as git. It took me awhile to get my head around it but now I would not go back to vanilla git.

Zed

I’m amazed that my IDE is not as important as other dev tooling. It was always number one on my list. That’s how much Claude Code has changed my ways of working.

I was a long time user of VS Code and before that Sublime Text. Zed reminds me of Sublime with its responsiveness. It’s a clean UI, packed with functionality. When they launched the debugger that was when I could make the full time switch from VS Code. I would use this editor alone for the Subtle Mode when using Edit Predictions.

It’s a great IDE. Typically these days I use to review a diff from Claude and do some light editing before either giving another prompt or committing the code.

Obsidian

My goto for note taking. The sync service is fantastic at syncing between my laptop and my phone. I keep all my notes here, from work to life to study. A great product.

Antinote

I love Obsidian but sometimes I just need scratch notes that are quick to hand. This is where Antinote shines. And if a scratch note does need to be saved it is easy to export it to Obsidian.

How I Use Every Claude Code Feature

Tue, 04 Nov 2025 07:38:55 +0000

This is a great read. Lots of information on how to use all the features of Claude Code. Lots here to go through and experiment with. In particular, I was wrong regarding the CLAUDE.md file and will look at the approach here to improve my use of this file.

Learning to Be a Coding Agent Babysitter

Sat, 18 Oct 2025 09:50:50 +0100

The past few months I have been learning to be an AI coding agent babysitter. Sometimes it works well, sometimes less so. Overall I feel like it has been a productivity boost. The sweet spot is in areas where I have good expertise, so I can tell if the agent’s output is good or not.

I’m still learning and trying to improve my babysitting skills. Here’s what I’ve learned so far.

Regularly clear the context

If I only had one tip, it would be this one. The key to clearing context regularly is to give really small and tightly defined tasks.

If the output isn’t what I want, I might edit some files myself or give a new prompt in the current context. Typically after a maximum of three or four prompts, even if the output so far isn’t what I want, I will clear the context and start over with a new prompt.

Use planning mode

I use planning mode to explore new areas of a codebase, to research a task or investigate possible areas where there might be a bug in the code.

When planning work and I have a good output from the agent, I use a snippet to ask it to tell the agent to “write this output as a markdown file in {dir}. Give the file an appropriate name and start it with today’s date {date:medium} in YYYYMMDD format”.

Use hooks

I have a hook with Claude Code that sends a notification when it needs me. For example, this users terminal-notifier on my Mac:

{
 "hooks": {
 "Notification": [
 {
 "matcher": "",
 "hooks": [
 {
 "type": "command",
 "command": "terminal-notifier -message \"Claude needs your input\" -title \"Claude Code\""
 }
 ]
 }
 ]
 }
}

This way, if I’ve switched focus, I am notified and don’t waste time with Claude doing nothing.

Another hook formats the code after Claude is done. This removes the need to include this in the prompt or worry about if the agent is going to ignore the instruction in the Claude.md to always format the code.

Write tests yourself

Leave Claude alone to write tests and the output is usually substandard. For example lots of duplicated test cases and tests that don’t even test production code. It could be a fragrant abuse of Mocks or by writing actual production code within the test and then asserting the code passes.

I will either write the tests myself, or at least the outline of the test and ask the agent to complete writing the test.

Whichever approach I go for, I always review the output. This is necessary for all code the agent writes but especially the tests. If your tests are bad, you can have even less confidence in the production code the agent writes.

Code reviews

After I’ve refactored, I will often ask Claude to do a code review of the diff. I do this in plan mode so my diff won’t be overwritten. It can sometimes provide some useful feedback that leads to a new prompt in a new context to refactor the code.

Agent MD files

I find these useful for two key reasons. When I’m new to a codebase, it’s a useful summary of the repo. An outline of the architecture, what is this repo about etc. Secondly, for the agent, it is useful to provide it with commands for running tests.

I’ve watched an agent try 3 different ways to run tests before I interrupt to remind it activate the Python venv first then run the test command. With this instruction in the Agent markdown file, this type of issue is greatly reduced.

Do these files help more than that? I’m not so sure, but I could be wrong. And all the providers always recommend it, so I still do it for every new repo I work on.

Multiple agents in parallel

I’ve read about engineers running multiple agents with git work trees. The bottleneck for me is reviewing the output and the context switching involved in that. Running two or more implementing agents is hard mental work so I do this in limited bursts.

What I do is research or planning tasks with one agent whilst I’m working on the implementation of another. It means once I’m ready to put the implementation work into pull request, I already have some research and a draft plan ready. I can review that in more detail and then start work.

I want to experiment and iterate with this area some more so I consider this area a work in progress for me.

ty the new new hope

Sat, 27 Sep 2025 10:10:07 +0100

This is a riff on my old post about uv. Astral have succeeded with ruff and uv. Can they also succeed with ty?

mypy is good and useful. If you accept the short comings of type annotations in Python. To me, it still feels like a bolt on to the language rather than a real part of it. In particular, when some libraries are not typed it can cause issues. My real issue? It is really slow.

Can Astral work their magic again?

uv reflections

Sat, 09 Aug 2025 08:35:09 +0100

Sometime ago, I wrote about my hopes for uv. It has surpassed my expectations. There isn’t always the time to migrate old projects at work, but for all future projects I by default reach for uv.

What I love is it has brought a “Cargo” like packaging experience to Python. Additions like uv run and uvx are also really useful.

The game change for me is uv venv. I no longer have to worry or care about installing different versions of Python. If I need to work on an older version of Python uv venv --python 3.10 will do the job, need a newer version uv venv --python 3.13. You get the idea.

What’s beautiful is if a Python version isn’t on my machine, uv venv will download and install it. The uv venv command has not only replaced my usage of the venv tool but also Python version management tools like pyenv.

uv is a great tool and another success from the team at Astral.

Adventures in Babysitting Coding Agents

Tue, 22 Jul 2025 19:57:40 +0100

This is a must listen. Will all Steve Yegge’s predictions come true? Only time will tell, but it is a fascinating conversation about the huge change we are seeing in software engineering right now.

I’m not entirely convinced that multi-tasking by babysitting multiple agents is the way ahead for me but I am certainly going to experiment. It is what persuaded me to try Claude Code. Let’s see how I get on.

Claude Code Hooks

Fri, 18 Jul 2025 06:49:14 +0100

With Claude Code, I recommend using hooks. A small but important step towards helping make the output more deterministic.

Claude Code

Thu, 17 Jul 2025 18:53:33 +0100

The past month or so I’ve been experimenting with Claude Code. It is the first AI/LLM tool that has given me some “oh fuck” moments. Genuinely impressed. And at the same time, it sometimes makes mistakes or writes terrible unit tests etc.

On balance though a useful tool. It helps me with my tasks but I can’t trust it entirely, I need to code review every single line of code it produces.

uv - the new hope?

Tue, 24 Sep 2024 19:09:11 +0000

I’m genuinely excited about uv, a new package manager and more for Python, from the creators and maintainers of ruff. uv started as a pip alternative and has now expanded to become closer to their aspiration of being Cargo (the Rust package manger) for Python.

Firstly, what excites me about uv is it has the potential to be one tool that replaces many. It has functionality to be an alternative to pip, poetry, pipx and pyenv.

Secondly, the speed of uv is incredible.

Last, and by no means least, what excites me is the workflows behind certain commands. For example:

If you have a uv project e.g. you have run uv init, then adding a dependency will auto create a virtual env if one does not already exist, activate it and install the dependency into it. All this by running uv add {pkg}.
If you invoke your script or app with uv run e.g. uv run main.py then uv will check the lockfile and virtualenv are consistent and run your Python code in the activated virtual env.

I think abstracting away the virtualenv like this can be really helpful to Python beginners. And I will really enjoy not having to remember some additional steps when trying to get something done.

All my personal Python projects will use uv from now on. I really hope it catches on and becomes the Python package manager.

Die zähen Gespräche haben ein Ende

Wed, 18 Jan 2023 19:47:01 +0000

Die zähen Gespräche haben ein Ende

The tough discussions have an end.

Yann Sommer is joining Bayern for EUR 8 million plus bonus payments. The Swiss keeper will sign a contract until 2025.

Thank goodness. Really couldn’t see Bayern winning anything this season without signing a top class keeper.

Will certainly make things interesting when Neuer gets back to full fitness. Of course, that should read if as there is no guarantee he can return to his previous exceptionally high standard.

Klimaterroristen, das sind wir doch alle

Fri, 13 Jan 2023 07:21:56 +0000

The title translates as “Climate terrorists, but that’s all of us”.

Some background. The article is about the “Unword of the Year” award for 2022. This annual award is ran by a language-critical campaign group originally launched in 1991. Klimaterrorist - climate terrorist in English - was selected as the “Unword” for 2022.

The newspaper Die Zeit had this to say:

Man muss sich den echten Klimaterroristen als recht normalen Europäer vorstellen. Morgens wacht er in einem aus Plastik und Furnier zusammengelatteten Möbelhausbett auf, dann duscht er 20 Minuten sehr warm, holt noch etwas Wäsche aus dem Trockner, verspeist ein paar Wurstbrote für die Freiheit und steigt sodann in sein Kraftfahrzeug. Mit dem gerät er irgendwo in einen Stau, den er so lange als schicksalsgegeben hinnimmt, bis er davon Wind kriegt, dass am Staubeginn ein paar Aktivistinnen auf der Straße hocken.

Dann wird er wütend und gebraucht böse Wörter, von denen eins nun von der sprachkritischen Aktion Unwort des Jahres zum Unwort des Jahres 2022 gewählt wurde. Dass es in diesem Fall nicht die boulevardesken Klimakleber sind, sondern die diskursiv etwas herausfordernderen Klimaterroristen, ermöglicht diesen Texteinstieg. Wie schon Klimahysterie für das Jahr 2019 lässt sich die Sache recht einfach umdrehen und gegen die richten, die das Wort eigentlich im Munde führen. Die Kopplung ist schließlich maximal unklar und allein das qualifiziert das Unwort als solches: Es ist sprachlich schlecht gemacht. Denn wer terrorisiert hier nun eigentlich wen oder was und in wessen Namen?

My translation:

You have to imagine the real climate terrorist as a fairly normal European. In the morning he wakes up in a plastic and veneer furniture store bed, takes a very warm shower for 20 minutes, gets some clothes out of the dryer, eats a few ham sandwiches in the name of freedom and then gets into his car. He gets into a traffic jam somewhere, which he accepts as fated until he gets wind of the fact that a few activists are squatting on the road at the beginning of the jam.

Then he gets angry and uses nasty words, one of which has now been chosen by the language-critical campaign ‘Unwort des Jahres’ as the Unword of the Year 2022. The fact that in this case it is not the tabloid climate stickers, but the discursively somewhat more challenging climate terrorists, makes it possible for this to be an Unword contender. Like ‘climate hysteria’ in 2019, the matter can be quite easily turned around and directed against those who actually utter the word. The linking of the words (climate and terrorist) is after all maximally unclear and that alone qualifies the Unwort as such: it is linguistically badly made. For who is actually terrorising whom or what and in whose name?

And this really is the clincher:

For who is actually terrorising whom or what and in whose name?

Town Complete Broadhead Signing

Thu, 12 Jan 2023 18:55:50 +0000

With Broadhead and Hirst signing, I’m genuinely excited at the additional firepower that Town have upfront now. It’s a strong squad. Here’s to us maintaining our promotion push this season.

Dev on the Road

Thu, 12 Jan 2023 12:25:57 +0000

I’ve always decided against getting an iPad because I want a machine I can develop on. There are good options in this post to make an iPad enough of a dev machine to fix minor emergencies if you are on the road. One of the options is using Gitpod.io. I’ve experimented with it before and was impressed.

Although if I had to choose between a MacBook or an iPad, I would still choose a MacBook.

Bring Back Personal Blogging

Thu, 12 Jan 2023 12:20:17 +0000

The biggest reason personal blogs need to make a comeback is a simple one: we should all be in control of our own platforms.

Amen. This was my motivation to revamp my blog this year.

Books I Want to Read in 2023

Tue, 03 Jan 2023 17:25:20 +0000

This year, like last year, I want to read some good software engineering books. These are the ones I currently have on my reading list:

Leading Snowflakes by Oren Ellenbogen
Modern Software Engineering by Dave Farley
Building Microservices: Designing Fine-grained Systems by Sam Newman
Machine Learning Engineering with Python by Andrew P. McMahon

Why do I want to read each of these books?

Leading Snowflakes by Oren Ellenbogen

As someone recently promoted to Engineering Management, albeit with prior experience working in management, I am keen to read books to help new engineering managers. I enjoy Oren’s newsletter and have read good reviews for his book, so that is why Leading Snowflakes by Oren Ellenbogen is on my list.

Modern Software Engineering by Dave Farley

This book has been recommended to me by several Engineers who I respect. This is enough of a reason to add it to my 2023 reading list.

Building Microservices: Designing Fine-grained Systems by Sam Newman

I really enjoyed and learned a lot from Saw Newman’s book Monolith to Microservices so in 2023 I want to read another book by him on microservices.

Machine Learning Engineering with Python by Andrew P. McMahon

This book interests me because I work to integrate machine learning into our product at work. I’m keen to read more about MLOps in particular but also to get more familiar with the parts of Machine Learning Engineering I don’t encounter every day at work.

Summary

This is my “minimum” list. I hope to read more software engineering and management books than this but if I only manage these then I shall still be satisfied.

Which books do you have on your reading list for 2023?

Docker Multi-Stage Builds

Sat, 06 Feb 2021 11:04:50 +0000

At work, we’re using Docker multi-stage builds to get smaller image sizes. I thought I’d try it out with a small learning project. The headline result is I reduced a Docker image from 305MB to 12.2MB.

# before
docker image ls
helloworldapi latest b24c966e9bgg 6 weeks ago 305MB

# after
docker image ls
helloworldapi latest f1f76e06146h 7 seconds ago 12.2MB

Multi-Stage Builds

How do multi-stage builds work? Every instruction i.e. line in a Dockerfile adds a layer to the image. A common practice was to have a development version of your Dockerfile which included everything you needed and a slimmed down version used for production. With multi-stage builds you don’t need to maintain two Dockerfiles. Instead you can use the syntax FROM ... AS <NAME> to name a stage, and then copy that named stage when you want want to use it. Only what is needed is brought across in this COPY and all the other layers are discarded. This results in smaller image sizes.

Here’s an example from the learning project I mentioned earlier. This is the Dockerfile before without using multi-stage. The image size was 305MB.

FROM golang:1.15.5-alpine
WORKDIR /app
COPY . .
RUN go mod download
RUN go build -o main .
CMD ["/app/main"]

This is the Dockerfile using a multi-stage, named as builder and used like this COPY --from=builder /app . i.e. copy the named stage into the /app directory.

FROM golang:1.15.5-alpine AS builder
WORKDIR /app
COPY main.go .
RUN go build -o main .

FROM alpine:latest
WORKDIR /app
COPY --from=builder /app .
CMD ["/app/main"]

As a result of using this multi-stage the image size is now 12.2MB.

Named Stages

Stages are not named by default and you can refer to each stage by an integer starting at 0 for the first FROM. So if the Dockerfile read FROM golang:1.15.5-alpine we could copy it across like this COPY --from=0 /app .. I prefer to use names as it makes it more obvious what is happening in the Dockerfile.

Target a Stage

How can you use multi-stage builds? When building an image you can target a stage. For example, a build stage named dev in a Dockerfile would be built like this:

docker build --target dev -t "${DOCKER_REGISTRY}"/${IMAGE_NAME}:"${IMAGE_TAG}-dev" .

The example above assumes variables are set for the Docker registry where the image is published, the image name and the image tag.

If the image is published then you can use this in Docker Compose:

service-name:
 image: $DOCKER_REGISTRY/$IMAGE_NAME:$IMAGE_TAG-dev

Alternatively, if the Dockerfile and source code are available on your local machine, you can target it like this:

service-name:
 build:
 context: path-to-service-name-source-code
 target: dev

Git Hook Prepend Commit Message

Sat, 11 Jan 2020 16:37:34 +0000

At work we have to add the Jira issue number to each pull request, branch and commit. This is to help Management with planning. Unfortunately for me, adding the Jira ID to each commit often broke with my existing workflow or I often just simply forgot to do add it. To remove this as an issue, how about a script to automate prepending the git commit message with the Jira ticket ID?

Git Hook Script

For the impatient, here’s the script.

#!/usr/bin/env python3

"""
Git hook to automatically prefix a git commit message with an issue number
(e.g. Jira ticket number) from the current branch name.
"""

import re
import sys
from subprocess import check_output


commit_msg_filepath = sys.argv[1]
branch = (
 check_output(["git", "symbolic-ref", "--short", "HEAD"]).decode("utf-8").strip()
)
regex = r"(chore|feature|fix|hotfix)\/(\w+-\d+)"

if re.match(regex, branch):
 issue_number = re.match(regex, branch).group(2)
 with open(commit_msg_filepath, "r+") as f:
 commit_msg = f.read()
 f.seek(0, 0) # correctly positions issue_number when writing commit message
 f.write(f"[{issue_number}] {commit_msg}")

First up, the script has some prerequisites and makes some assumptions:

Requires Python 3
Git branches follow the convention of using chore, feature, fix or hotfix, a / followed by the Jira issue number (e.g. EX-100) and then the “branch name” e.g. feature/EX-100-example-branch-name.
Assumes there are valid branches that do not require this script to run e.g. at work release branches do not contain a Jira ticket ID.

With that out the way, let’s walk through the script and see what it does.

The shebang is important because we need to make sure this script executes using Python 3. Per the Python docs, “a good choice is usually #!/usr/bin/env python3”.

Next is a docstring to remind myself several months later what this script does. Then the imports required for the script. All imports are from the standard library so no need to pip install anything.

The variable commit_msg_filepath is a system argument passed into the script. We use this later on, opening it as a file to write the commit message.

We find the branch name by using subprocess.check_output

From the Python docs:

Run command with arguments and return its output. By default, this function will return the data as encoded bytes.

It runs the git command git symbolic-ref --short HEAD and the return is decoded to a string and stripped of whitespace.

The regex pattern for the git branch naming convention is declared as the regex variable. This allows the script to extract the Jira ID. This script is lenient so if there is no match, it assumes there is a valid reason for the branch not having a Jira ID. If the regex has a match we enter the if block. This is the code which amends the commit message.

The Jira issue number is group 2 in the match regex. It opens the commit message as a file and reads in the contents of the file.

seek() is an interesting one. If writing a commit message in vim then seek(0, 0) places the Jira ID as the first part of the commit message placeholder. Comment out seek(0, 0) and you’ll see the Jira ID half way down in the git commit message verbiage yet it will still get written as the first part of the commit message. That’s because the final line writes the actually git commit message e.g. after you type it, save and exit Vim the message gets written as [EX-100] example commit message.

Using the script

Finally, to make this script work there are two options.

Option one is to add to a single repo or to each repo you want this script to run. This wasn’t an option for me as we have many micro-services which I might work on and didn’t want to add the script to each repo.

Option two is to point global git config to a directory of your git hooks. This is what I went for and here’s how to do it.

Global Git Hooks

Save the script in a directory where you keep or plan to keep all your global git hooks. Make sure the script is executable chmod +x prepare-commit-msg.

Then run this to point the global hooks to your directory:

git config --global core.hooksPath /path/to/git_hooks

Run cat .gitconfig to check the output:

 │ File: .gitconfig
───────┼────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
1 │ [user]
2 │ name = Sam Atkins
...
5 │ [core]
6 │ hooksPath = /path-to/git_hooks

Final thought

Here’s a link to the script on Github. Thanks for reading.

Using Docker Commands with Aliases and Bash Functions

Sun, 13 Oct 2019 07:06:45 +0100

We use Docker at work and so I find myself running the same commands over and over. To save time I saved frequent docker and docker-compose commands as aliases and functions.

Aliases

These aliases save a few key strokes for running often used commands:

# general compose aliases
alias dcb="docker-compose build"
alias dcu="docker-compose up"
alias dcub="docker-compose up --build"
alias dcs="docker-compose stop"

# list all running containers
alias dps="docker ps"

# stop all running containers
alias dsa="docker ps -q | awk '{print $1}' | xargs -o docker stop"

# list dangling images
alias dlist="docker volume ls -qf dangling=true"

Functions

Some commands are better saved as functions.

When developing and writing unit tests, I will often want to get to the bash prompt in the test container. I saved this function as dcbash.sh and aliased it as dcbash to save a few keystrokes:

#!/bin/bash

# Run a bash shell in the specified container (with docker-compose)

# a simple help menu: if no arg is passed in, the function usage is printed
if [ $# -ne 1 ]; then
 echo "Usage: $FUNCNAME CONTAINER_NAME"
 return 1
fi

# this echo is optional but I like to maintain familiarity with the actual command
echo "CMD: docker-compose run --entrypoint="" $1 /bin/bash";
docker-compose run --entrypoint="" $1 /bin/bash

For example dcbash pretend-service-test runs docker-compose run --entrypoint="" pretend-service-test /bin/bash.

Images take up space and are not auto removed. I’ve encountered errors before about lack of space so a periodic tidy up of unused images and containers is recommended.

I saved this as drmi.sh and it removes dangling Docker images:

#!/bin/bash

# remove docker dangling images
docker rmi $(docker images --filter "dangling=true" -q --no-trunc)

I saved this as drmc.sh and it removes all non-running containers:

#!/bin/bash

# removes all non-running containers
docker rm $(docker ps -q -a);

These aliases and functions help my productivity by saving a key strokes and saving time looking up the commands for a periodic tidy up of Docker images and containers. I hope they may prove useful to you too.

Hugo Pipes

Sat, 28 Sep 2019 13:47:05 +0100

Hugo version 0.43 introduced Hugo Pipes which processes assets e.g. save preprocessed Sass files to CSS files. I finally got round to adding this as part of adapting the Ghostwriter theme I use on my site (a forked Ghostwriter theme by Juraj Bubniak.

Why Hugo Pipes and not Webpack

The theme had a webpack build for the Sass files which could be replaced by Hugo Pipes. This was attractive as it simplified the build process for my static site and removed webpack and a whole load of dependencies I no longer need to worry about keeping up-to-date.

How I added Hugo Pipes

The first step was to move the Sass files to a top level directory called /assets.

The second step was to add this pipeline:

{{ $style := resources.Get "sass/main.scss" | resources.ToCSS | resources.Minify | resources.Fingerprint }}
<link rel="stylesheet" href="{{ $style.Permalink }}">

For organisation, I added the above to a new partial called layouts/partials/styles.html and then included this partial into the header.html partial using partialCached.

{{ partialCached "styles.html" . }}

Why use partialCached?

allows for caching of partials that do not need to be re-rendered on every invocation

After some testing to check it worked, the final step for local development was the happy task of deleting the webpack config and associated files.

In terms of deploying, I use Netlify and there turned out to be one gotcha.

error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version

The issue per this post from Netlify is due to an older version of an Ubuntu image which was incompatible with the version of Hugo. In order to use Hugo Pipes you need to make sure you are using the new Ubuntu image. If you recently set up a Hugo site on Netlify this new Ubuntu image is the default. My site has been on Netlify for some time so I needed to go into the settings and select the new Ubuntu Xenial build image.

With that done, I re-deployed and this time the deploy went through and everything worked.

Empty Git Commits

Wed, 18 Sep 2019 20:13:56 +0100

Some build pipelines have steps which are only triggered if a certain phrase is contained in the commit message. The problem is sometimes e.g. after a code review there may be nothing to commit but you need to start this build process.

Try doing an empty commit in VS Code and a warning message says “there are no changes to commit”.

The solution when you need an empty commit is to use the allow empty flag and add the commit message you need:

git commit --allow-empty -m "[magic build]"

In the example above the string [magic build] triggers additional steps in the CI build. Problem solved.

Reflections on DevOps Barcelona 2019

Tue, 23 Jul 2019 20:08:21 +0100

In June I attended a DevOps conference in Barcelona. Whilst I work in web development, I have a growing interest in DevOps which is mainly due to my previous career in supply chain and lean. This was a key motivation for attending: to learn more about different people’s experiences with DevOps.

I’ve had these high level thoughts sat in “draft” for a while so thought I’d smarten them up a bit and post to my blog.

Summary

First up, it was a well run and good conference. I enjoyed that it was single track as there’s no feeling of missing out if two talks scheduled at the same time are of interest. Lots of good speakers and I’m full of admiration for everyone that presented, especially the majority doing so in a second language.

As for the talks, there were several that really resonated with me.

DevOps Culture

Nationwide had two good talks on culture and building teams from Marc Cluet and Aubrey Stearn. It’s always exciting to hear about tools but people and culture are the foundation of DevOps. Both talks were excellent examples of how Nationwide are building a great DevOps culture.

Security

Shout out to Néstor Salceda at Sysdig for an impressive demonstration of Falco. Falco is a “behavioural activity monitor designed to detect anomalous activity in your applications”. Néstor Salceda’s demo was great because he demonstrated how the container was stopped once anomalous activity was detected. Very impressive.

Managing Failure in a Distributed World

The best talk in terms of execution and the slick demo was by Nic Jackson (and his colleague whose name I sadly can’t find in my notes) from Hashicorp about Managing Failure in a Distributed World. A very slick demo showed how multiple cloud providers could be used to ensure improve latency but also as a fallback if one cloud provider has an outage, traffic can be switched to another cloud provider.

Testing in Production

My favourite talk was Alex Soto’s (Redhat) talk on testing in production. This was a real eye-opener and definitely something to read more on. It was controversial to me because I’d aways read and experienced directly at work that you have multiple stages e.g. dev for general development of features, QA or staging for testing of features and bug fixes before deploying to production.

The approach outlined in the talk is all development is done in production behind feature flags. Internal users can toggle if they see production or beta/alpha development e.g. feature or bug fixes. As I understand it this approach extends from CI and trunk based development where all work is merged directly to trunk but behind feature flags until it is ready for prime time.

The key benefit of the approach Alex outlined is that you only need to have one stage, namely production. However he warned it is very hard to and to start slowly. I still have a lot to learn so this idea is still quite scary to me, but the idea is eye opening and makes me rethink my previous assumptions on how things should be done.

Final Thought

And finally, Barcelona is a beautiful city and I want to visit again. 😎

2 years as a professional software engineer

Mon, 15 Jul 2019 20:09:10 +0100

Time really does fly. As I write this, I have unlocked the two year milestone of working as a professional software engineer. It only feels like a short time ago I set myself the goal of changing career and becoming a professional software engineer. I feel incredibly privileged to have had the opportunity to change careers, to be working for Big Health and working in web development.

I was discussing with a friend at work some tips he was collecting for a friend of his who was just starting out as a professional web developer. I thought it would be useful exercise to post an expanded write up of the advice that would have benefited me just before starting my job. My hope is that this may also prove useful to others.

Learn how to learn

There is one constant in this career and that is you should always be learning. Find out the most effective ways for you to learn in a sustainable manner and keep learning.

Don’t reinvent the wheel

I learn best by building stuff but there isn’t time to build everything. Give less weight to reinventing things and doing a lot of coding, and more attention to reusing other tools and investigating what’s out there.

Dealing with imposter syndrome

Don’t compare yourself to other developers. Remember your own journey and progression. A trick I use to remind myself how much I have learned is to keep a journal of achievements. This keeps me grounded as I know I still have a lot to learn but looking at my journal I can see I have learned a lot in my 2 years as a professional software engineer.

Hone your problem solving

Improving your problem solving skills will help with bug fixes and in general working in web development. I found this a good article on problem solving.

Broaden your horizons and stay up to date

Listening to podcasts and reading blogs are a good way to immerse yourself in the latest developments, get familiar with terminology, and learn about how other engineers think and work.

In addition to finding good podcasts and blogs, read some of the best programming books out there to get familiar with best practice programming principles, software design and other important topics which interest you. Here’s a post on some good books I ready last year (two of the books were recommend to me by my VP of Engineering).

It’s not just about the code

Soft skills are important. If you’re a career changer like me your soft skills you’ve developed will stand you in good stead. When you work as a professional programmer, you won’t be coding all day every day. You’ll be interacting with other people on a daily basis. Don’t neglect your soft skills.

Understand process

I’ll admit I’m a process geek but even for those who are bored by process, realise that at work process will impact how you and the team work, and it will be a major influence on how effective the team is. Whilst it will differ at each company, we follow Agile, with daily stand-ups and sprints, and follow GitHub flow as part of a release train process. Process is important and getting familiar with the basics e.g. how to open a GitHub pull request will help you get up to speed.

Focus on what to learn

Focus on a few areas rather than trying to learn everything.

There’s a mountain of stuff to learn so have a plan. Something that really helped me to put some structure around my learning and a path to follow was freeCodeCamp, followed by Udacity Nanodegrees. You can choose a different education provider - and there’s lots of high quality out there - but following a curriculum put together by experts will help you to focus. This applies to getting your first software engineering job but I would also argue for continuing your ongoing learning.

An additional good resource to help guide learning activities are these developer roadmaps.

Avoid burnout

Software engineering is a tough job. The temptation - with me at least - was to code at work and then do coding learning projects in my spare time. Whilst I still do this to an extent, it’s also important to be able to step away and recover and recuperate.

Have a hobby to get away from the mental stresses of coding. Spend time with your friends and family. Exercise. Seriously, do lots of exercise. This is a good read on how to stay fit physically and mentally.

Pipenv and Poetry package managers

Sun, 14 Apr 2019 09:09:58 +0100

Python is a wonderful language for beginners but I remember when starting out how Pip, the defacto package manager for Python (at least at the time) didn’t seem as fully featured as others such as npm. Having to manually update requirements.txt or remember some other command to get it updated seemed an oversight. Add to that the need for virtual environments due to the whole Python 2 vs Python 3 thing and it can hinder new programmers from getting up and running with a Python project.

That’s why the additions of Pipenv and Poetry have been welcome. I’ve now used them for some of my own learning projects and am impressed with them both. Here’s my quick overview of them.

Pipenv

Brought to you by Kenneth Reitz, the same author as requests, Pipenv combines the functionality of Pip and a tool like virtualenv. Through a few simple and intuitive commands, you can create a new virtual environment, install packages and Pipenv handles creating and managing your requirements in Pipfile and Pipfile.lock files.

I use it for some scripts I’ve written and I’m a huge fan.

Poetry

Poetry is used to help you manage libraries you are developing. It also has a few simple and intuitive commands to manage the dependencies in your project, including one to scaffold out a directory structure with starter files for your library. However, you will still need to use something like virtualenv to manage the version of Python you are using. Poetry uses a pyproject.toml and poetry.lock for the dependencies. I like this file format and the real strength is the pyproject.toml file can be used instead of setup.py to manage the packaging of your library to PyPi - Python Package Index.

I only have the one experience of creating a package available on PyPi but found using Poetry very useful during this process.

Conclusion

Both are good additions to the Python ecosystem, and provide good alternatives to the Python programmer. It’s important to remember the distinction in use cases for the two. As it says in Pipenv’s documentation:

There is a subtle but very important distinction to be made between applications and libraries. This is a very common source of confusion in the Python community. Libraries provide reusable functionality to other libraries and applications (let’s use the umbrella term projects here). They are required to work alongside other libraries, all with their own set of subdependencies. They define abstract dependencies.

Which should you use? To me that depends on the use case.

Scripts: use Pipenv
Libraries: use Poetry
Applications: use Pipenv (or Docker)

In most cases when building an application as part of a learning project, using Docker makes most sense for me. I’ve had some issues with Pipenv working in Docker (some strange caching issues that I didn’t have time to get to the bottom of), so when I’m using Docker I combine it with Pip and a requirements.txt file. It is entirely likely the Docker/Pipenv issues was something I set up incorrectly so using Pipenv and Docker might be a good combination for you.

To conclude, in my opinion Pipenv and Poetry are great tools and welcome additions to the Python ecosystem.

Code Snippets in VS Code

Sun, 17 Mar 2019 17:17:10 +0000

Adding code snippets in your IDE are a great way of saving key strokes on code that you often use.

In Python specific IDEs such as PyCharm, enabling docstrings is built-in and available via preferences. I prefer using VS Code as I don’t just code in Python and generally prefer it as my IDE. But you don’t need to lose out on this small piece of functionality because that’s where creating your own code snippets comes in.

For those who don’t code in Python, and are asking what is a Python docstring? Here’s the official definition:

A docstring is a string literal that occurs as the first statement in a module, function, class, or method definition

You can read more about docstrings here.

Here’s how to set up a code snippet in VS Code, using the Google style of docstring as an example.

In the menu bar select: Code -> Preferences -> User Snippets

Select Python from the menu. This opens a file called python.json

In this file add the following:

"Python docstring": {
 "prefix": "_docstring",
 "body": [
 "\"\"\"${1:description}\n\nArgs:\n\t${2:param name} (${3:param type}): ${4:describe the param} \n\nReturns: \n\t${5:type}: ${6:description}\n\"\"\""
 ],
 "description": "Python docstring - Google style"
}

This snippet example outputs the following:

"""description

Args:
 param name (param type): describe the param

Returns:
 type: description
"""

What does the syntax in the actual snippet mean?

The key Python docstring is the name of the snippet
The prefix is what you type in order to trigger the snippet
The body is the output of the snippet once triggered
The description is displayed whilst typing and selecting a snippet

Within the body of the snippet the items with the syntax ${1} are very helpful. The cursor will tab through each of these so you can overwrite the placeholders. In the example above, first of all “description” is highlighted and when you type you can overwrite this text. Hit tab and the cursor will move to “param name”, tab again and “param type” and so on.

I find snippets a small but powerful way of increasing productivity and reducing my frustration. I hope this helps you to add snippets in VS Code and increase your productivity too.

Update

The above example shows how to create a snippet but is actually not a good example. If you want to semi-automate creating Python docstrings in VS Code then I recommend the extension Python Docstring Formatter.

Command Line Git Aliases

Mon, 11 Feb 2019 19:39:18 +0000

Working with version control is a must for good software development. I use git personally and at work. The GUI in VS Code is good for some git work e.g. viewing diffs. However, for some tasks it is fast and productive to use the command line.

There are some commands that are very useful but are too long to type each time i.e. they are good candidates to save as an alias. For example:

# Command to switch to master branch, fetch and pull latest from remote
git checkout master && git fetch && git pull origin master

# Command to push all commits to remote from your local branch
git push origin $(git_current_branch)

# Command to fetch and pull all commits from remote to local for your current branch
git fetch && git pull origin $(git_current_branch)

# Pretty prints the git log. I typically use when I have merged a feature branch to master and want to find the commit as part of then tagging the release
git log --graph --pretty='\''%Cred%h%Creset -%C(yellow)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset'\'' --abbrev-commit --all

Setting up aliases

There are several options to set these up as aliases. This is how I did it on a MacBook.

bash profile

In your .bash_profile which is in your home directly i.e. ~/.bash_profileadd the aliases.

An example for git fetch and pull:

alias ggpull='git fetch && git pull origin $(git_current_branch)'

When I type the alias ggpull in the command line, the command git fetch && git pull origin $(git_current_branch) will run.

zsh

If like me you use zsh, add the below to the to the bottom of .zshrc. This ensures all your git alias goodness in .bash_profile is available even if you use zsh.

if [ -f ~/.bash_profile ]; then
 . ~/.bash_profile;
fi

My preference is to keep all my aliases in .bash_profile for forward compatibility. If I were to stop using zsh or want to use these aliases on a Linux machine then I already have my bash profile file ready.

I hope this is helpful in setting up some of your own aliases and saving a few keystrokes each day.

3 Recommended Programming Books

Wed, 23 Jan 2019 07:00:27 +0000

As I reflect on 2018, there were three programming books I enjoyed reading and learned a lot from. I thought I would share my summary of each book.

The Pragmatic Programmer by Andrew Hunt and David Thomas

Recommended to me by my boss, this is a timeless guide to programming. Programming and technology moves fast, yet despite being written in 1999 this book is still relevant today. In my opinion, the fact this is the case shows just how important the principles the book teaches are. This book really helped me with understanding programming best practices and how I can build those best practices into my daily work. It’s a reference to keep coming back to as I progress in my programming career.

Coders at Work by Peter Seibel

Another recommendation from my boss, this is a series of interviews with incredible programmers. It is interesting reading about the different approaches these programmers take to their work.

Of particular interest was reading the contrasting and complementary philosophies and approaches of Brendan Eich and Douglas Crockford when discussing developing the JavaScript language.

I also enjoyed reading about Brad Fitzpatrick and his incredible blend of programming skills and business/open source acumen with LiveJournal and Memcached as great examples of this.

And from a broader industry perspective a very topical and important theme, reading about Fran Allen’s experience of the how the industry became male dominated and her views on the importance of increasing diversity.

The DevOps Handbook by Gene Kim, Jez Humble, Patrick Debois, John Willis

This was probably my favourite programming book I read last year. It’s full title is The DevOps Handbook:: How to Create World-Class Agility, Reliability, and Security in Technology Organizations

My background, prior to switching careers, was in Supply Chain and Operations (in the manufacturing sense) including lean and process optimisation work. This book was a real eye opener, taking a manufacturing operational view to building software. The book explains how a DevOps culture looking at People, Process and Tools can drastically improve a software company’s performance, in terms of speed to market and software resilience.

The insight that infrastructure as code is actually the most important aspect to use version control (rather than as I had previously assumed for development code) was a huge point but once digested makes sense. If you have an interest in DevOps and how teams work to build software, I highly recommend this book.

Pytest Tricks: Freezegun and Parametrize

Mon, 05 Nov 2018 19:38:08 +0000

I always try to work following Test Driven Development. I recently used Pytest to write some unit tests and discovered a couple of neat tricks from a work colleague.

Context

I needed to write a function which determined if a user’s account had been created within a specified time window. The function returns a boolean i.e. true if the account was created within the time window and false otherwise.

Here’s a function I wrote (amended to remove any work sensitive information):

from datetime import datetime, timedelta

TIME_WINDOW_DURATION = timedelta(minutes=30)


def _check_if_user_created_in_time_window(self, account_creation):
 """
 If the user's account creation time falls within this time window,
 return True

 Parameters
 ----------
 account_creation: timestamp
 Timestamp of when user's account was created

 Returns
 -------
 bool
 True if tag to be applied, False otherwise
 """
 account_creation_datetime = self._cast_datetime_string_to_datetime_type(
 account_creation
 )
 now = datetime.utcnow()
 user_gets_tag = now - TIME_WINDOW_DURATION <= account_creation_datetime <= now
 return user_gets_tag

Writing tests

Writing tests when you have to match against a timestamp is tricky because it could create fragile tests. In other words, a test that may or may not pass, and the pass or failure does not tell you if it is the code failing or because the timestamps do not match.

So the first tip is to use freezegun. This allows you to effectively set the date and time when the system is under test so you can make assertions against the function.

Here’s an example of this in practice:

@freeze_time("2018-09-07 16:35:00")
def test_user_created_in_time_window_returns_true(client):
 example_manager = Example()
 account_creation = "2018-09-07 16:05:01"

 user_gets_tag = example_manager._check_if_user_created_in_time_window(
 account_creation
 )
 assert user_gets_tag

The freeze_time decorator sets the system under test date time as 2018-09-07 16:35:00 so when we assert an account creation time of 2018-09-07 16:05:01 it falls within the time window of 30 minutes i.e. evaluates to true.

As you would expect, I wanted to make different assertions based on different frozen times and so wrote another test like the above but with a different date time passed in as the argument to the decorator. That’s all well and good as it tests the code but it goes against the DRY (don’t repeat yourself) principle.

So here’s the second trick I learned:

@pytest.mark.parametrize(
 "account_creation", ["2018-09-07 16:34:00", "2018-09-07 16:05:01"]
)
@freeze_time("2018-09-07 16:35:00")
def test_user_created_in_time_window_returns_true(client, account_creation):
 example_manager = Example()

 user_gets_tag = example_manager._check_if_user_created_in_time_window(
 account_creation
 )
 assert user_gets_tag

Pytest - per the docs - “enables parametrization of arguments for a test function”. So how does this work?

Like freeze time, you wrap the unit test with a decorator which takes two arguments. The first is a string which is the name of the argument. This should also be passed in as an argument to the test function. The second argument is a list of the parameters. In the example above, I’ve added two different date time strings as parameters. This means when the test runs, it will run twice, using the first parameter and then the second. This keeps the code DRY whilst allowing multiple assertions. What’s also neat is when you run the tests with verbosity pytest -vv the output displays the test being run along with the parameter used. The unit test above displays:

test_example.py::test_user_created_in_time_window_returns_true[2018-09-07 16:34:00] PASSED
test_example.py::test_user_created_in_time_window_returns_true[2018-09-07 16:05:01] PASSED

Two nice tips to help write good unit tests and keep the code DRY.

Python Getters and Setters

Mon, 08 Oct 2018 20:31:40 +0100

At work recently I had to add some getters and setters to enable user’s responses to a question being persisted to the database. A few new things came up so to reinforce my learning, I decided to write this.

Context

The issue arose when trying to handle a list of the user’s answers to a question. Let’s say the question was “What sports to do you like?” and the user can answer either one or several of “football, basketball, tennis, rugby, cycling” or just “none of the above”.

If the user were to choose football and cycling, a Python list would be part of the client request to the API.

["football", "cycling"]

Trying to persist this list to the database led to an operational error:

OperationalError: (OperationalError) (1241, 'Operand should contain 1 column(s)')

The reason for this error is SQL databases cannot store lists. Relational databases are designed specifically to store one value per row/column combination.

Each value should be stored in its own database column. However due to various business and technical reasons, it was decided this was not the right option in this case.

So this is where getters and setters come in.

What are getters and setters?

Getters and setters allow you to protect your data by controlling who can do what to the data. For each variable, a get method “gets” the value and the set method “sets” the value.

Getters and setters example

For my use case, the getters and setters were actually fairly straightforward. Manipulating a string to a list and back again.

Here’s an illustrative example.

class ExampleSportsQuestion(BaseModel):
 _sporting_interests = db.Column("sporting_interests", db.String(150))

 @property
 def sporting_interests(self):
 """
 Get sporting_interests
 """
 if self._sporting_interests is None:
 return []

 return list(self._sporting_interests().split(","))

 @sporting_interests.setter
 def sporting_interests(self, list_sporting_interests):
 """
 Set sporting_interests
 """
 sporting_interests_choices = [
 "football",
 "basketball",
 "tennis",
 "rugby",
 "cycling",
 "noneOfTheAbove",
 ]
 for interest in list_sporting_interests:
 if interest not in sporting_interests_choices:
 raise AttributeError(
 f"Invalid value {interest} for " "_sporting_interests property"
 )

 string_sporting_interests = ",".join(list_sporting_interests)
 self._sporting_interests = string_sporting_interests

The getter in this example creates a list, splitting the string using a , comma as a delimiter.

# starting point is this string which is the value persisted in the database column
"football,cycling"

# the getter transforms it to a list
["football", "cycling"]

If the database entry is None then defensively the getter returns an empty [] list.

The setter checks the user’s answers are in the available choices and if not, raises an error. If the answers are all valid, the list is converted to a string with each answer separated by a , comma.

# the setter does the reverse, it takes the list provided by the client
["football", "cycling"]

# and transforms to a string to be persisted in the database
"football,cycling"

And that’s it. Along with some unit tests, this provided the solution and was ready for code review.

It was useful to go through the process of exploring this topic, reading about relationship databases and normalisation, possible use cases for getters and setters, and how to implement Python getters and setters. Writing this up in a blogpost has helped to solidify my learning, and I look forward to reading this again sometime in the future to see how much I’ve learned since this was written and how much I agree/disagree with it 😁.

Converting a React App to TypeScript

Fri, 20 Apr 2018 00:00:00 +0000

Learning some TypeScript has been on my to do list for sometime. I finally found some time and started by reading the docs to get familiar with it. The next step to really help learn it was to actually use it for a project so I decided to convert an existing React app to use TypeScript. This blogpost is a guide on how I did exactly that.

First up: Wow, developing with TypeScript is amazing. Most definitely #iHeartTypeScript !

And now let’s get started.

First things first: React app with TypeScript configuration

To make things simpler I used create-react-app with TypeScript flags in order to scaffold a React app with a TypeScript config. My thought process was I could this config in my existing React app and it abstracts away the whole Webpack configuration (another thing on my learning list by the way).

This is the command to run to get a TypeScript React app:

npx create-react-app TypeScript-app --scripts-version=react-scripts-ts

This is basically a fork of create-react-app: https://github.com/wmonk/create-react-app-TypeScript

Configuration

Now I had a TypeScript config, I used this in my existing React app as a first step to converting it.

First up I created a new git branch git checkout -b convert-to-TypeScriptfor my work. Now I could replace the React app config with the TypeScript config, and work through the errors until the app compiles:

copy over all the ts files e.g. tsconfig.json
copy over the scripts and dependencies into package.json

I can’t live without Prettier code formatting so to get Prettier to live happily with TSLint formatting I will add the TSLint-Config-Prettier package like thisyarn add tslint-config-prettier --dev

And add a .prettierrc file so Prettier formatting is aligned to TypeScript linting.

// .prettierrc.yaml

parser: TypeScript
singleQuote: true
trailingComma: all
semi: true

And for complete sanity, I deleted the node modules then installed all dependencies again with yarn install to make sure everything is installed as it should be.

Get the app to compile

With the config in place, it was time to try running the app and see what happened i.e. what errors I would get.

So yarn start and let the fun begin.

Missing index.tsx

Failed to load tsconfig.json: Missing baseUrl in compilerOptions
Could not find a required file.
Name: index.tsx

This was two different errors. The second about the “required file” was a simple fix. TypeScript was looking for a TypeScript file as an entry point i.e. file index.tsx. I changed the existing entry point index.js to index.tsx.

For the other error, it seems the config I copied over was not quite right so I added the missing baseurl in compiler options in tsconfig.json like this:

{
 "compilerOptions": {
 "baseUrl": ".",
 }
}

No default export

The error read:

// path shortened for brevity purposes:
(3,8): Module '"... /myreads/node_modules/@types/react/index"' has no default export.

This was a common issue across multiple files. The fix was straightforward in terms of syntax:

import React from 'react'; needs to be import * as React from 'react'; and then fix how the class is declared class BooksApp extends React.Component instead of class BooksApp extends Component.

In addition, in the same file I had import ReactDOM from 'react-dom'; which needs to be import * as ReactDOM from 'react-dom';

Now the harder part. Why was this an issue for TypeScript? And how did the fix work?

After some research, here’s what I learned. The React package (and many other packages) don’t actually have a default export. Instead they have named exports. So why doesn’t this work with TypeScript? Basically it’s a difference between how Babel and TypeScript handle this. Babel is used by create-react-app to compile the JavaScript and it creates a synthetic default export from all of the named exports, whereas TypeScript doesn’t follow this approach.

So in TypeScript you need to import everything and then use the named export when required. For example, to use the React Component named export you would do this:

import * as React from 'react';

class BooksApp extends React.Component {
 // ... snip
}

Convert to Types

OK, good progress made because the app compiled but other than the config and the entry point index.tsx there was no TypeScript in sight. Next step then was to convert the next JavaScript file to a TypeScript file and after the entry point, the first component is App.js.

I changed the filename App.js to App.tsx, restarted my development server (yarn start) and started working on fixing the type errors.

A side note, as part of my development process, in tsconfig.json I sometimes toggled the setting "noImplicitAny": false, between true and false. This was to allow/disallow any types in order to check what needs type checking versus getting the App to compile. The aim is to have this set to true for complete type checking but it’s sometimes useful to have the app compile and check how things are working before going back to check any types.

Convert App.tsx

The first type error was the books array on my state object:

... /myreads/src/App.tsx
(17,17): Parameter 'book' implicitly has an 'any' type.

// code:
state: = {
 books: [],
}

To fix this I added an interface to set the contract for state should look like. I set both the books and shelves array as optional i.e. ? denotes optional. The reason for making this optional is the initial state is empty until the component has mounted, i.e. the API returns data.

// file: /myreads/src/interfaces/stateProps.ts

export interface StateProps {
 books?: object[];
 shelves?: object[];
}

In addition, I created an interface for the book object:

// file: /myreads/src/interfaces/bookObject.ts

export interface BookObject {
 allowAnonLogging: boolean;
 authors: string[];
 averageRating: number;
 canonicalVolumeLink: string;
 categories: string[];
 contentVersion: string;
 description: string;
 id: string;
 imageLinks: {
 smallThumbnail: string,
 thumbnail: string,
 };
 industryIdentifiers: [
 {
 type: string,
 identifier: string,
 },
 {
 type: string,
 identifier: string,
 },
 ];
 infoLink: string;
 language: string;
 maturityRating: string;
 pageCount: number;
 panelizationSummary?: {
 containsEpubBubbles: boolean,
 containsImageBubbles: boolean,
 };
 previewLink: string;
 printType: string;
 publishedDate: string;
 publisher: string;
 ratingsCount: number;
 readingModes: {
 text: boolean,
 image: boolean,
 };
 shelf: string;
 subtitle: string;
 title: string;
}

and used it like this:

updateBook = (book: BookObject, shelf: string) => {
 // snip
};

The next compile error was this:

/myreads/src/App.tsx
(72,11): Value must be set for boolean attributes

The <Route /> component takes prop exact to match an exact url path. Before the return statement, I declared exact as a constant and set the type to a bool like this: const exact: boolean = true; and then as before pass in exact={exact} to the component.

The next error related to my method to update books and the args passed into it. Here’s the error and how I fixed it:

// error
/myreads/src/App.tsx
(74,30): Parameter 'shelf' implicitly has an 'any' type.

// Update code to fix the error
onUpdateBook={(shelf: string, book: BookObject) => {
 this.updateBook(book, shelf);
}}

💥 BOOM 💥

App.tsx fully converted to TypeScript! A small celebration and then I continued converting other files to TypeScript.

Converting a .js to a .ts file

In other words, utils/BooksAPI.js to utils/BooksAPI.ts.

Next up I took on a straight JavaScript to TypeScript conversion with no JSX. Converting this file involved stating the types for the args to each of the functions. I also re-used the BookObject interface:

// after
export const update = (book: BookObject, shelf: string) =>

export const update = (book: BookObject, shelf: string) =>

export const search = (query: string, maxResults: number) =>

String or array of string types?

This demonstrates the usefulness of TypeScript.

The compile error was this:

/myreads/src/containers/Book/Book.tsx
(15,31): Parameter 'writers' implicitly has an 'any' type.

OK, easy I thought and added a string type. Wrong! But the error messages are so helpful!

index.js:2177 /myreads/src/containers/Book/Book.tsx
(19,42): Property 'join' does not exist on type 'string'.

So of course it’s not a string, it’s an array of string types. I corrected the code like this:

const formattedAuthorStr = (writers: string[]) => {
 if (writers === undefined) {
 return writers;
 }
 return writers.length >= 2 ? writers.join(', ') : writers;
};

Synthetic Events

Parameter ’e’ implicitly has an ‘any’ type.

const handleMoveBook = e => {
 const selectedBook = props.book;
 const selectedShelf = e.target.value;
 onUpdateBook(selectedBook, selectedShelf);
};

My solution:

interface MoveBookEvent {
 target: {
 value: string,
 };
}

const handleMoveBook = (e: MoveBookEvent) => {};

And then two other interfaces to manage the props in the component. The first for what is passed into to the component, and the second for managing props which are passed back up to update a book when moving it between bookshelves.

interface BookProps {
 authors: string[];
 shelf: string;
 title: string;
}

interface BookComponentProps {
 book: {
 authors: string[],
 shelf: string,
 title: string,
 };
 bookImgUrl?: string;
 onUpdateBook(book: BookProps, shelf: string): void;
}

// usage
const Book = (props: BookComponentProps) => {};

SearchPage Component

This was an interesting compile error. This was the first Class I was dealing with and so it was a little different from some of the other stuff I’d looked at.

The TypeScript compile error was this:

/myreads/src/App.tsx
(76,15): Property 'books' does not exist on type 'IntrinsicAttributes &
IntrinsicClassAttributes<SearchPage> & Readonly<{ children?: ReactNode; }> ...'.

After a bit of searching and docs reading I found a few things that helped to solve the issue.

First up, from the TypeScript docs re generics and generic classes:

A generic class has a similar shape to a generic interface. Generic classes have a generic type parameter list in angle brackets (<>) following the name of the class.

Next, a React class requires a generic class in the form of <props, state>. Within each of these generic classes, you state the types. In the end I used interfaces for props and state which I added next to the class like this React.Component<SearchPageProps, SearchPageState>

The full example is here:

interface SearchPageProps {
 books: BookObject[];
 onUpdateBook(book: BookProps, shelf: string): void;
 onSelectSearchPage(): void;
}

interface SearchPageState {
 error: boolean;
 userSearch: string;
 updatedSearchResults: string[];
}

class SearchPage extends React.Component<SearchPageProps, SearchPageState> {
 // snip
}

This resolved the type compile errors.

Node Module React-Debounce-Input ‘placeholder’ text

This one puzzled me for a few hours late one evening. In the end, I shut down my laptop and went to bed. In the morning, a possible solution came to me whilst I was having breakfast.

Key lesson here: don’t code when tired, take a break and get plenty of good sleep.

So the error that caused me so many problems was this:

Property 'placeholder' does not exist on type 'IntrinsicAttributes &
IntrinsicClassAttributes<Component<ThemedOuterStyledProps<WithOptionalTheme...'.

It’s on a node module react-debounce-input used as part of the search functionality. Here is the code as used in the SearchPage.tsx component.

<Styles.SearchBooksBarInput
 minLength={2}
 debounceTimeout={300}
 onChange={e => handleUserSearch(e)}
 // the line below was causing the TypeScript error
 placeholder="Search by title or author"
 value={this.state.userSearch}
/>

The solution was to add to this line readonly placeholder?: string | number; in this file node_modules/react-debounce-input/src/index.d.ts:

export type DebounceInputProps<
 WrappedComponent,
 WrappedComponentProps
> = WrappedComponentProps & {
 readonly element?:
 | string
 | React.ComponentType<PropConstraints<WrappedComponent>>;
 readonly type?: string;
 readonly onChange: React.ChangeEventHandler<WrappedComponent>;
 readonly onKeyDown?: React.KeyboardEventHandler<WrappedComponent>;
 readonly onBlur?: React.FocusEventHandler<WrappedComponent>;
 readonly value?: string | number;

 // new type added on the line below
 readonly placeholder?: string | number;

 readonly minLength?: number;
 readonly debounceTimeout?: number;
 readonly forceNotifyByEnter?: boolean;
 readonly forceNotifyOnBlur?: boolean;
 readonly inputRef?: React.Ref<WrappedComponent>;
};

This fixed the TypeScript compile error because previously TypeScript was looking for the property placeholder on the object and couldn’t find it.

Having fixed it in the dependency, I wasn’t then sure how to keep my changes. I found a good answer on Stack Overflow:

Send a PR to the actual npm package, if the change is like a bug fix or enhancement that aligns with the actual packages goal.

Fork the package repo, and make changes and use it in your project as a dependency, in case you are adding changes that does not align with the goals of the actual package

Move the package code into your source code, and use it as source code rather than a package from npm

I decided to try out option 1 first and see what happened. I opened a PR to the repo… and it was quickly accepted and merged.

By the way, that was my first code contribution to an open source project. 🏆

Other stuff

Using console.log

As part of my development process, I wanted to use console.log() but this causes TypeScript to fail to compile due to a TSLint error. Rather than change the config and then potentially make git commits with console logs still in the code, I opted for this instead to temporarily disable TSLint:

/* tslint:disable */
console.log(this.state);
/* tslint:enable */

VS Code config

Finally, some thoughts on using VS Code with TypeScript.

One recommended config change is to set this setting to true in your user settings:

"TypeScript.implementationsCodeLens.enabled": true,

This means you’ll see the number of implementation of your interfaces in your code e.g.

TypeScript and VS Code really play well together, as you would expect, I mean VS Code is written in TypeScript. VS Code becomes even more IDE like and it’s really productive to work with TypeScript in VS Code. I’m a huge fan of both.

Summary

To conclude, using TypeScript is a fantastic development experience and it achieves this by:

boosting my developer productivity, and
improving even further VS Code’s capabilities

It was good fun converting my React app to using TypeScript. When I find time I will convert some other React apps to use TypeScript.

Next up, convincing the team at work to use TypeScript! 😏

Udacity React NanoDegree reflections

Fri, 23 Mar 2018 00:00:00 +0000

Image: React.js Nanodegree

I completed my third Udacity Nanodegree in January 2018. This time the subject was React and React Native. It was a very rewarding yet demanding course. I’m glad I did it, learned a lot from completing it, but am glad it’s over - I get my evenings and weekends back.

I find it helpful to reflect on what I learned, what worked well and what didn’t, to help with my learning in the future. So here are some key reflections on the Nanodegree.

Match the tool to a need

The first project was a Book reading app called MyReads. The lessons and project deliberately specified using only React to manage the app’s state. That’s right: no Redux. 🙈

Why? To make you understand why you should use Redux, and why you shouldn’t. In other words, when is a tool useful, what purpose does it serve? And will my use case be met by using this tool?

So the first project involved passing state down from component to component aka “prop drilling”. For the most part, this wasn’t an issue, with a couple of exceptions which were a bit painful. It also becomes clear if the app grew in complexity, then something like Redux would be a useful addition to the project’s dependencies.

The second project was Readable, a reddit type clone, built with React and Redux. This was a more complex app and the project reinforced the message in the lessons on the benefits that Redux would bring to the app.

Over the course of these two projects, the point was made about the benefits (and downsides) to using Redux. Applied more generally to programming, I think this is a useful lesson to make sure it is clear what the requirement is and then to search for the right way to fulfil it.

An important lesson: Learn to know when to use a tool and when not. If it doesn’t fit your use case, then don’t use it.

Debugging

I was reading an old blogpost of mine and I read this statement:

the power of using console.log()

Debugging is a skill that I still need to improve on. Bug fixes at work are a necessary part of the job and it’s a great feeling when you find and fix a bug.

The React Nanodegree helped me to learn some far more powerful ways of debugging when developing:

Using the debugger in Virtual Studio Code or Chrome devtools to add breaks in order to step through the code. Understanding the value of a variable at a certain point in time, seeing how and when different functions get called and with what values, is really powerful and an order of magnitude more powerful than the plain old console.log()
Using Redux devtools and Redux logger to see exactly what is going on with the state of the app, when actions and reducers are getting called, and how state is being updated (but not mutated of course)

Rubber ducking

The Nanodegree provides you with a mentor who is available for weekly check ins, and also ad-hoc questions in between. I found it very helpful to have a mentor. Most of the time I found my interactions with my mentor were rubber ducking.

Rubber duck debugging or rubber ducking is a phrase based on a story in the excellent book The Pragmatic Programmer in which a programmer would carry around a rubber duck and debug their code by forcing themselves to explain it, line-by-line, to the duck.

This was a powerful technique for me and really helped on numerous occasions. The process of explaining the issue helped me to understand it better and usually as a result of this I found a solution presented itself.

In addition to that I should add my mentor was extremely knowledgeable and helpful, as well as a good rubber duck listener.

Learning style and approach

I like the combination of video explanations, complimented with text based learning, solidified by implementing what I’ve learned during the course lessons. The mentor plus code reviews make this broadly similar in some respects to working professionally as a web developer. I learned a lot and really enjoyed the course.

The downside to the course is it was very time intensive. Udacity are very upfront about the time requirements but with a full time job, and a family life outside of work, the need to study for about 10 hours per week is a large commitment. Now I’ve completed the course, I can say it was a worthwhile investment, however I will look to study in smaller, bite size chunks for the foreseeable future. 30 minutes a day reading a technical book, or practising with some new code, or building a new little project piece by piece is more manageable and over time should still prove effective.

Summary

All in all, an excellent course and it has helped to improve my React and React Native skills considerably. In addition, I learned some important broader aspects to being a software engineer which I can apply regardless of the language / library.

Setting up ESLint and Prettier

Sat, 10 Feb 2018 00:00:00 +0000

Set-up ESLint and Prettier

I’m a big fan of linting and I love the configurability of ESLint with the auto formatting capabilities of Prettier. It’s been a revelation. Learning best practices in terms of ESLint rules and formatting from Prettier, plus no more bikeshedding at work in pull requests on coding style. Let the machine take care of it for you.

Each time I set-up a new JavaScript project, I set-up this configuration in my editor of choice Visual Studio Code, so this blogpost is my step by step guide to remind myself how to implement ESLint and Prettier to work in VS Code.

Specifics

Before diving into the detail, a few points:

I install the config for each project locally as I prefer that level of control to fine tune for a project’s specific needs.
Yarn is used as the package manager but swop out the equivalent npm commands if preferred.
As mentioned above, the final step includes VS Code configuration but check Prettier’s docs for set-up with different editors.

Install ESLint

Step one is to install ESLint with the AirBnB style guide config. In order to do this, follow the instructions from AirBnB:

If you use yarn, run npm info “eslint-config-airbnb@latest” peerDependencies to list the peer dependencies and versions, then run yarn add –dev @ for each listed peer dependency.

For example:

➜ ~ npm info "eslint-config-airbnb@latest" peerDependencies

{ eslint: '^4.9.0',
 'eslint-plugin-import': '^2.7.0',
 'eslint-plugin-jsx-a11y': '^6.0.2',
 'eslint-plugin-react': '^7.4.0' }

Based on this info, the install command would look like.

yarn add --dev eslint babel-eslint eslint-plugin-import@^2.7.0 eslint-plugin-jsx-a11y@^6.0.2 eslint-plugin-react@^7.4.0

You’ll notice the install of eslint and babel-eslint in addition to the AirBnB config.

Once complete, add a .eslintrc.yml to the root of your project and add the config from the dotfiles template repo.

Install Prettier

Next up, install Prettier and some plugs so it all plays nicely together:

yarn add prettier --dev --exact
yarn add --dev prettier eslint-plugin-prettier eslint-config-prettier eslint-config-airbnb

This is important because both ESLint and Prettier will try to format code which we don’t want. Instead we want Prettier to format the code based on the ESLint rules defined in the .eslintrc.yml file.

VS Code extensions and settings

The final step is to configure the editor so it plays nicely with the project’s ESLint and Prettier config.

These steps are specific for VS Code. First, install two extensions:

Second, add these user settings (CMD + , to open user settings):

// My personal preference; set for JS only to avoid formatting other file types
 "[javascript]": {
 "editor.formatOnSave": true
 },

// This stops VS Code from trying to autoformat code
"javascript.format.enable": false,

// This one is obvious, right?
"prettier.eslintIntegration": true,

That’s it. Your project is ready to be linted and formatted.

Becoming a professional web developer

Wed, 08 Nov 2017 00:00:00 +0000

Photo by Rohit Tandon on Unsplash

A few years ago I decided to transition career and become a professional web developer. Married, with a young son, and a full time job as a management consultant (i.e. long hours and lots of travel) this was not an easy undertaking. Yet - 🎉 👍 - as I write this now I have worked as a professional full stack engineer for six months.

This blogpost is the advice and tips I wish I’d had at the beginning of my learning journey, and I hope some of these prove useful to you too.

Know your goal and be focussed on what you learn and when

I’m curious in nature and always like to play with shiny new things. Whilst this has advantages, there are clearly disadvantages such as getting distracted and not working on moving closer to your actual goal. Early on when learning I would often dive off into a rabbit hole learning something which whilst perhaps useful didn’t directly get me to my goal: becoming a professional web developer.

My solution was to develop a flexible framework with specific goals and objectives to reach my goal. Completing the Intro to Programming Udacity Nanodegree was an early objective. Anything that wasn’t directly related to this I questioned, asking myself “what will I gain my doing this?”. It stopped me on several occasions from wasting time on unnecessary diversions. Sometimes though I would allow myself to learn something which was useful, fun (it should always be fun) and would indirectly benefit me to reaching my goal. For example, I learned some Gulp which wasn’t part of any qualification but it taught me about web development processes and helped improve my productivity, automating some key processes.

So if you’re like me, then pick what you learn and work on carefully and make sure it’s moving you forwards.

Find your learning style

Related to knowing your goal, find out how you learn best and put some structure around your learning in order to reach your goal.

Let’s unpack that statement.

Curriculum

What I mean by this is putting some structure around what you learn. I credit freeCodeCamp with providing initial structure for me to learn some of the basics of web development and most importantly at the time that I really enjoyed it and wanted to pursue it as a career.

At Udacity I studied two Nanodegrees, first the Introduction to Programming to build on the basics I learned from freeCodeCamp. Next I studied the Full Stack Nanodegree and I credit this fantastic course as being instrumental in successfully transitioning career to become a professional web developer.

In fact, I’m such a fan of Udacity that at the time of writing I’m studying my third Nanodegree on React, Redux and React Native, but more on this another time.

Mentor

I need community and people to turn to help guide me in the right direction. Learning to code is hard, but with the right support you can learn. I will always appreciate freeCodeCamp because it helped me to discover coding but I found the self directed nature of freeCodeCamp wasn’t for me. Udacity on the other hand with mentor support and code reviews was a much better fit. A mentor/coach system worked wonders for me. So find what works for you and go with that.

Learn by doing

I’m no good just working on learning algorithms just for the sake of learning an algorithm. I get they are important, and learning some is very important. But just trying to learn them on their own I quickly find boring. Only doing Codewars isn’t for me. I learn best my doing. Build something and work out along the way the best way to do this. Sure this means knowing your mapfrom your reduce from your filter but use them whilst you’re building a project.

Build stuff

The best way to learn to code is to code.

I don’t know who this quote can be attributed to but I wholeheartedly agree with it. It builds on my point above to learn by doing.

Once you’ve got some of the basics of HTML, CSS and some JavaScript, then start to build things. For me it is undoubtedly the best way to learn. I built lots of project apps, initially as part of following freeCodeCamp, then as part of my Udacity Full Stack Nanodegree, and then also some others independently.

As you progress, complement this with learning more about your language of choice. For example, one of my favourite parts of Wes Bos’ excellent JavaScript 30 course is array cardio - learning to work with array methods.

Use abstractions to your advantage

There’s an absolute ton of stuff to learn. It’s impossible to learn it all. So lean on others for some of the heavy lifting. A great example of this is I started learning React a few months ago. Using create-react-app to create a React app with no build configuration (e.g. not having to worry about WebPack) is awesome. Just run create-react-app my-app and then get coding in React.

In other words, be smart about what you learn. I want to learn about WebPack but for me personal there’s more benefit to learning React and React Native first.

Be professional

I had no complete idea of what it meant to be a professional web developer and six months in I’m still learning huge amounts everyday on what it is and what it means. But you can make some assumptions based on blogposts and articles and build that into your learning.

Having technical expertise and writing good code is just one part of it. Writing good documentation, using git and a service such as GitHub, working proficiently with your editor/IDE of choice in a local environment are just some of the parts of being an engineer. This means during your own studying, you could for example:

Write great documentation in your project READMEs
Use git and Github (or Gitlab, Bitbucket if you prefer). By the way, if you find git on the command line intimidating, then use a GUI such as GitKraken or SourceTree. Just start using git as soon as possible!
Develop locally rather than an online service such as Codepen. There is nothing wrong with Codepen and there’s some fantastic stuff in there. It’s also a great way to abstract away alot of the set-up. At the same time I quickly became frustrated with using it as my develop environment and so…
Pick an Editor/IDE e.g. Sublime, Atom, VS Code etc and configure it to your liking and master it’s functionality, key bindings etc. I much prefer using my editor because I can set it up how I like and work efficiently.
Use a linter e.g. flake8 for Python, ESLint for Javascript

Market yourself

Showcase your ability, commitment and ability to learn. I have learned a lot since I started coding, and have learned even more in six months working as a web developer. My knowledge feels like a drop in ocean compared to my more experienced colleagues. But I think one of the reasons I was hired was my desire and ability to learn. Just writing this on a CV or saying this in an interview won’t get you very far, you need evidence to back it up. And this is where Github (or similar service ) comes in to play. It’s a marketplace for you, your projects, your code, your documentation and your desire to learn.

So start using git today already!

Join a community

Learning on your own can be tough. Seek out community for people also learning to code. This could be with the organisation you’re learning with e.g. freeCodeCamp or Udacity. Or if you’re following your own path, or to complement them, definitely check out CodeNewbie and the 100daysOfCode hashtag on Twitter organised by @ka11away. Both communities are superb and very supportive.

Immerse yourself

Get familiar with terminology and what developers talk about, as well as emerging trends and technologies. I find Podcasts are a great way of doing this. I listen to podcasts on my commute to work and it’s a good way of relaxing but still learning. There’s lots of great podcasts out there but some personal favourites are:

Reading news, articles, blogposts and email newsletters are further good sources of information to help keep abreast of latest developments. Some recommendations include:

What are you afraid of?

Best advice I've heard and followed re my career: “What would you do if you weren't afraid?

My motivating force was thinking “where do I want to be in 5 years time?”. I was nervous about changing careers but the fear of being stuck in the same job in 5 years time was a far bigger fear. In other words, doing nothing was a bigger risk than attempting to change careers. I set a plan, had some contingency and fall back options and went for it.

Think what your motivating force is and use that to remind yourself of why you are doing this. I kept a log of my achievements, however minor or trivial, so in moments of despair I could look at it and remind myself of how much I had already learned, and the progress I was making to achieve my goal.

So make a plan, get learning and I look forward to welcoming you in the future as a fellow professional software engineer.

100 Days of Code Challenge Summary

Mon, 28 Aug 2017 08:15:16 +0000

Photo by Sai Kiran Anagani on Unsplash

Earlier this year I completed the 100 days of code challenge. A few Twitterers suggested I write a summary of my 100 day coding challenge experience. Better late than never, here is my summary of the challenge which capped off months of previous hard work, to the extent that I am immensely proud of what I achieved over the 100 day challenge and the first quarter of 2017.

To summarise, my key achievements and projects were:

Key Achievements

Udacity Full-Stack Nanodegree graduate.
Built a portfolio with several projects (listed below).
And saving the best until last, I managed to transition my career into professional web development by landing a fantastic role at as a Junior Full Stack Web Developer at Big Health.

Main Projects

Udacity:

Neighbourhood Map (Knockout.js)
Catalogue app (Python, Flask)
Multi-user blog (Python)
Portfolio site (HTML, JavaScript)

Self-learning:

Pomodoro clock (React.js)
Markdown previewer (React.js)

What I learned

Forming a habit

The habit of coding everyday is invaluable. It helps with learning. It also helped me to realise that coding everyday was a joy and not a chore.

Workflow

Balancing work, life and studying (including the 100 day challenge) is hard. I wanted to make sure that whenever I was coding, I was efficient and actually coding. So taking the time to learn about workflow and how to make it more efficient is very worthwhile. Learning git and Gulp, setting-up an editor and other such things made me far more productive.

Read the docs

I remember the Catalogue Item project from my Nanodegree as the first real time that I was able to pretty much refer to official documentation to help build functionality for my app. Getting to grips with technical documentation and learning how to apply it to your own code was a big moment for me.

Be professional

If you are like me and want to change career, then work as professionally as you can immediately. I soaked up lots of the Udacity free video courses to try and work on hygiene factors e.g. using git for version control, learning about and implementing good documentation practices (e.g. always have a README, and be thorough in what you document), using Gulp to automate my workflow etc. Read up on what professional web developers actual do and then attempt to replicate that for your coding. This is a key reason I originally switched from using Codepen (as suggested for a lot of the FreeCodeCamp exercises and projects) to Sublime Text, and git and GitHub.

The hard work starts now

The 100 day challenge taught me a lot. I used it as an opportunity to learn and help drive my focus to transitioning my career into becoming a professional web developer. Having completed the challenge and changed career, I now the hard work over my entire career starts now, and doesn’t end. I’ll blog more on making the transition and starting out as a junior developer in future posts.

Neighbourhood Map Project

Sat, 18 Feb 2017 10:15:16 +0000

This post relates to a front-end JavaScript and Knockout.js MVVM project, using APIs from Google Maps and Foursquare. The GitHub repo is here, and a demo is live on surge.sh.

Context

I’m writing about my Neighbourhood Map project for one main reason. It has been a really hard project, and the best way to learn about it is to write about it.

Before I dive into the detail, this blog post is primarily aimed at present and future me. As I mentioned above, it is to help with my learning but also for me to look back on and see how I worked through this project.

If anyone else does read this post and notices any technical JavaScript errors or areas I could improve upon, please let me know. I am passionate about learning and would love to hear from you.

Design

The key part of this project is to use the Model View ViewModel (MVVM) design paradigm. Part of the rubric stipulated using Knockout.js, a JavaScript organisational library.

First I had to get my head around how the architecture of the app, using the MVVM paradigm. The rubric from Udacity for the project stated:

Code is properly separated based upon Knockout best practices (follow an MVVM pattern, avoid updating the DOM manually with jQuery or JS, use observables rather than forcing refreshes manually, etc). Knockout should not be used to handle the Google Map API.

My emphasis on the final sentence. This is the part that threw me, although I interpreted it too literally. Knockout should be used to manage the View (UI) and connect to the Model via the ViewModel, but Google Maps API should be used to handle the actual aspects of the map.

My 1:1 session with the Udacity coach helped to put things in perspective, and at this stage, whilst planning is important, over analysis and designing too complex an architecture (for my skill level) is not good. Better to plan, build, get things working, then refactor later as appropriate.

I followed the MVVM design based on the lessons and the mini project (cat clicker) to get up and running.

Then I was into the challenge full on.

Problems and solutions

This is not an exhaustive list but pulls out some of the key problems I faced and how I solved them.

Managing Foursquare JSON responses

Resolving the issue where Foursquare does not always have the info for each venue e.g. one venue has a description and a price range, another venue does not. This caused the infowindows to throw errors and not open.

Solution:

A forum post recommended using ‘hasOwnProperty` - MDN: hasOwnProperty
For example:

var venues = result.response.hasOwnProperty(“venues”) ? result.response.venues : “”;

if (venues != “”) {
 // do something
} else {
 // do something else
}

Allowing a user to filter an array

Ideas and inspiration on how to solve this came from a few sources.

First of all, a blog post by Ryan Niemeyer on Utility functions in KnockoutJS. This in particular was the idea behind options to filter an array, combined with indexOf (see this from MDN re Array.prototype.indexOf()).

Secondly, as the first options were not providing a completed solution, in the end, via one of the forum mentors, this link to a KO Maps example provided the inspiration I needed.

This gave me ideas on how to solve not just this challenge but also creating a favourites list. To fully understand it, I picked it apart, studied it, slept on it, and then developed a plan how I could make it work for a user filtered list and also for a favourites list.

Plan

In essence, the approach is to create an array, then an observable array based on the original array. The user filter input - from the data-bind textInput() - is used to filter the observable array. In short, this is how to create a list which can be filtered by user input but which shows as complete (i.e. has the contents of the original array) if no user input is detected.

The next challenge is to link the filtered list to the rendering of the location markers. The Google Maps API includes setVisible(bool) for the location markers. So the logic which determines what is in the observable array then also needs to switch the location marker to setVisible(true).

Implementation

I stepped through trying to get my plan to work and encountered a few errors along the way:

Issue 1: Cannot locate the markers

Error: Uncaught TypeError: Cannot read property 'setVisible' of undefined

So tried to add this.marker = null; to my Constructor as the marker was not part of my Model i.e. not in the constructor to add a property when instantiating an object.

Issue 2: null ain’t it

Error: Uncaught TypeError: Cannot read property 'setVisible' of null

Nope, that’s not quite it although thinking it through, I still believe I need this object property.

Issue 3: Need to refactor how I instantiate my objects

Why? So locationItem.marker is available to my runAttractionFilter function.

This solved it. It works! 😀 👍

Solution

I split out the functions like this:

Create an array, instantiating new objects.

Add to this array of objects with further information, using separate functions, crucially without the keyword new. In other words, add to the existing objects, do not create “new” objects.

This allows the mirrored observable array to render the list in the html file (via foreach: arrayName) and it shows a complete list.

As soon as the user starts to search, the filter is applied via the databind=“textinput: userFilter”. In addition, a KO keyup event is added to the data-bind so the function managing the observable is run after each keyup.

console.log('attractions are below');
console.log(self.attractions);

// search and filter an array based on user input

// set-up empty observable array for visible attractions
self.filteredAttractions = ko.observableArray();

// populate visible attractions array with objects from attractions array
self.attractions.forEach(function(locationItem) {
 self.filteredAttractions.push(locationItem);
});

console.log('filtered Attractions are below');
console.log(self.filteredAttractions());

// set user filter as ko observable
self.userFilter = ko.observable('');

// filter function: updates observableArray and
// sets visibility of location markers
self.runAttractionFilter = function() {
 var searchFilter = self.userFilter().toLowerCase();

 // 1. clear the array
 self.filteredAttractions.removeAll();

 // 2. run the filter and only add to the array if a match
 self.attractions.forEach(function(locationItem) {

 // set marker to false i.e. invisible
 locationItem.marker.setVisible(false);

 if(locationItem.name.toLowerCase().indexOf(searchFilter) !== -1) {
 self.filteredAttractions.push(locationItem);
 }
 });

 // for each item in the array, set visibility to true i.e. visible
 self.filteredAttractions().forEach(function(locationItem) {
 locationItem.marker.setVisible(true);
 });
};

Favourite locations

Attempt 1: Using KO Observables

First, I need to plan how to set the object properties and observables.

Add this.favourite to my constructor, with a default value false.

HTML data-binds: In a similar way to the toggle functionality for my responsive menu, I plan to toggle the css styling for the favourite icon.

this.toggleFav = ko.observable(false);

When a user clicks on the favourite icon, this will call the function manageFav() which will switch toggleFav observable from false to true, or true to false.

It will also activate a CSS style to change the icon e.g. from black to yellow.

Then an observable array, originally based on the attractions array, will repopulate. Only truthy fav observables will be pushed into this new array.

This observable array with truthy properties will be used with a data-bind foreachto iterate a list in the index.html page.

Issues

HTML data binds must be in the html file, not in the JavaScript contentString used to render the contents of the infowindow.

This is my test. It worked as below but move the html snippet into Javascript i.e. the var contentString which informs the rendering of the marker’s infowindow and it doesn’t.

// html file
 <div class="fav">
 <i data-bind="click: favouriteAttractions" class="fa fa-star" aria-hidden="true"></i>
 </div>

// js file
this.favouriteAttractions = function( {
 console.log('You clicked on the star');
}

Attempt 2: Using Google Maps API for ‘rightclick’ on the marker

Let’s explore the Google Maps API docs for some insight.

Google Maps JavaScript API V3 Reference | Google Maps JavaScript API

Second best option is to go for a rightclick event using the Google Maps API. I don’t like the UX of the right click, although it’s a lot less clunky than a double click which I also tried but it really didn’t work at all.

I ran this to test it:

locationItem.marker.addListener('rightclick', function() {
 console.log('right click on marker ' + locationItem.name);
 self.favouriteAttractions(locationItem);

self.favouriteAttractions = function(locationItem) {
 console.log('You want to favourite ' + locationItem.name);
}

Then built up the code for a favourites list.

I added favourite to the Constructor with a falsy default:

this.favourite = false;

Then an if statement to toggle truthy to falsy, and vice versa.

Then I built an observable array to store the favourites, which only pushed to this array if locationItem.favourite == true.

In the HTML data-bind I added a foreach: favAttractions.

After some backwards and forwards resolving console errors, I got it working but with one bug.

The array rendered as a list and it duplicated the entries e.g.

I like venue 1; renders venue 1.

Then I like venue 2; renders venue 1, venue 1, venue 2.

Hmmm…

After some experimenting, I realised I needed to clear the array before repopulating with venues where locationItem = true.

Summary

That’s it. Project complete! It feels great to have built something which tested my skills so thoroughly.

My key takeaways from this project are:

Plan but do not over plan. Better to have a good plan, then build some code which can be refactored later.
Use the power of console.log(). It’s an invaluable way of determining what is actually going on, if your code is doing what you think it is, and it really helped with my understanding of how my code behaves.
Try to keep things simple. Sometimes easier said than done but strive for it nevertheless.
Read the docs!
Try to solve the problem yourself but after a certain point, ask for help/guidance i.e. someone experienced to point you in the right direction.

Thanks for reading. I hope this proves useful (to future me) to see how I tackled a difficult project.

Sublime Text 3 and Python

Sun, 08 Jan 2017 10:15:16 +0000

As I wrote recently, after jumping between Javascript, GoLang and Python, I’ve decided to heed some good advice and focus on one language for awhile. And that language is Python.

This post is about my Sublime Text 3 set-up for programming in Python.

As an aside, this post is about getting your machine set up to manage different Python projects - Managing Python Projects with Virtualenv.

Why Sublime Text?

Whilst I’m still a fan of Atom, the number one reason I switched to Sublime is speed. As a beginner, it’s a little bit harder to set-up and get to know than Atom but still completely worth it.

The best way to get to grips with the power of Sublime text is to check out Wes Bos’ superb course on Sublime Text.

So what are the must-have Python packages for Sublime?

Packages

Package Control - this is not Python specific but in general. It makes installing / removing packages really easy. To browse for packages go to Package Control - the Sublime Text package manager.

Anaconda - this is a really powerful package for linting and autocomplete, amongst many other things. It also has a Build System (Tools - Build System - Anaconda Build System) for running Python scripts within Sublime Text where appropriate.

Terminal - not just for Python but this is useful to run Python in a Terminal inside Sublime. It is also an alternative to the Anaconda Build System.

Theme and colours - an excellent way to live browse different themes and colours directly in Sublime Text is to use the Colorsublime package. Although theme and colour is of course very much a subjective and personal choice, my current favourite for coding in Python is:

Theme: Boxy Monokai
Colour Scheme: Flatland Monokai

And that’s it. Thanks for reading!

100 Days of Code

Sun, 01 Jan 2017 10:15:16 +0000

I’ve joined the #100DaysOfCode Challenge. Over Christmas I decided to focus in Q1 2017 on completing Udacity’s Full-Stack Nanodegree. As part of this, a complementary objective is I want to really get to grips with Python.

When I read about the #100DaysOfCode challenge I thought it was an ideal way of holding myself accountable for my Q1 objectives. It will reinforce the habit of coding every day and helping to learn Python. I also hope to get involved in and contribute to the programming community and make some friends along the way.

tl;dr

Q1 2017 Objectives:

Complete Udacity Full-Stack Nanodegree
Continue to learn the Python programming language
Complete the #100DaysOfCode challenge*
Contribute to the programming community
Build some sh*t

(*Well, 87 days actually but I can complete the challenge in April.)

Follow Me

My log recording each day’s progress is on Github.

Managing Python projects with Virtualenv

Fri, 30 Dec 2016 10:15:16 +0000

Python 2 versus 3

To summarise the Python wiki:

“Python 2.x is legacy, Python 3.x is the present and future of the language.”

More info is available on the Python wiki.

Why use Python 2?

Wherever possible, use Python 3. However, sometimes Python 2 may be necessary and per the Python wiki the two key reasons are likely to be: deploying to an environment you don’t control so it may impose a specific version of Python if you want to use a third party package or utility which does not have a Python 3 compatible version

Running P2 and P3 on macOS

macOS comes with Python 2 pre-installed. I believe it is used in the Operating System. As a result of this, even if you want to use Python 3, you should not try to uninstall Python 2. At least this is my summary of some Stackoverflow articles and I’m not going to experiment to find out if they are right or wrong. It is actually fairly straightforward to install Python 3. Downloads for Python 3 are available at Python.org. This downloads an installer with GUI instructions on how to install.

Another option is to use brew e.g.

$ brew install python3

Once Python 3 is installed, use which to check Python is installed correctly.

$ which python
/usr/local/bin/python
$ which python3
/usr/local/bin/python3

The results should show Python is in the above directories. If this is not the case, the installs may not be correct.

Intro to Virtual Environments

I read more and more support is becoming available for Python 3 but for example the Udacity course I’m following is still using Python 2, and Google Cloud still requires Python 2 (at least from my beginner’s understanding so I might be wrong on this one). Either way, how do you manage manage dependencies if you are switching between Python 2 and 3?

VirtualEnv to the rescue. Virtualenv is a tool to create isolated Python environments. It allows you to use packages and utilities within a virtual environment i.e. “has its own installation directories”

My documentation

The documentation for using Python and virtualenv is dispersed across multiple sites, in particular regarding managing projects in Python 2 versus 3. The primary purpose of this blogpost is a consolidation of various things I’ve found for my own future reference.

How to use virtualenv

The below refers to using Python 2. Separate Python 3 instructions follow after.

Start a project repo as per normal:

mkdir new-python-project
cd new-python-project

Once inside the project directory, run the command virtualenv env

env is the directory to place all the virtualenv good stuff. This name can be changed but I always leave this as the default so I know exactly what this is. It also has the small advantage that env is already included in the Github Python .gitignore template, saving a few keystrokes to get your git repo up and running.

pip

To install package dependencies, you first need to activate the virtual environment.

The command is:

$ source env/bin/activate

This must be run from within the project directory.

To save some typing, I saved activate as an alias in my zsh alias config.

To deactivate, simply type the command deactivate.

Requirements.txt

Add a pip requirements.txt file to the root of your project directory. To do this type the command pip freeze pip freeze > requirements.txt

This is similar to a package.json file for Gulp with all your packages and dependencies. It makes it possible to duplicate the project using the same dependencies. For example, by running pip install -r requirements.txt you would install the specific package dependencies.

Python 3

To set-up a Python 3 amend the virtualenv command as below:

virtualenv -p python3 env

Activate and deactivate work as above. Make sure to activate the virtual env prior to installing any packages and utilities but also to ensure your code is executed correctly. Without the virtualenv being active, your system may look to run the default Python install i.e. Python 2 and your code may not execute.

Thanks for reading. As I mentioned, the main purpose of this is a consolidation of useful information I found in order to manage Python and virtual environments for my projects. Should anyone else read this, and spot any improvements or corrections, please let me know. Otherwise, I hope it may also prove useful to other readers.

Installing Tree on OSx

Mon, 19 Sep 2016 10:15:16 +0000

This is how to install Tree on macOS in the Terminal.app. It assumes Homebrew is installed. Homebrew is a package manager for OSx.

To install run this command using Homebrew: brew install tree

Now that it is installed, here’s how to use it:

# Useful to run this to test it installed properly and displays help
tree --help

# Lists all files and directories
tree -a

# Shows the tree of specified directory
tree -a <directory name>

# Lists directories only in the pwd
tree -d

Thoughts

An aside, previously I never really understood the power (and thrill) of using the command line. It’s relatively simple to install and use this binary, and yet it gave me such satisfaction from discovering tree to instal/use. I think this is a sign that pursuing learning to code is the right thing for me.

Why I'm using Hugo static site generator

Sun, 18 Sep 2016 10:15:16 +0000

Encouraged by a conversation with Andy @ Udacity, I made the decision to start a technical coding blog with a focus on helping me to learn more and document my coding journey.

I did waver if this was the right thing to do but this and this helped convince me to go ahead.

The next decision was then how to set-up it all up.

DIY

It was immediately clear to me I wanted a Do It Yourself option. I wanted a project to help develop my technical learning rather than just using Wordpress.com or Medium to share my views, opinions and learnings. (Although I think I may experiment with posting some blogs on these sites as well.)

Having blogged before using a self-hosted Wordpress.org site I didn’t want to go down that route again. I’m a big fan of Wordpress, especially if your site is more than just a blog. But page load times, the admin of having to upgrade for security, was all too much for what I wanted to be just a simple blog site.

Static site generators

Whilst on Github I noticed the option to set-up a GitHub Page, with their preferred option of Jekyll. This sounded really interesting.

To digress for a moment, this is a good explanation of what a static site generator is.

I narrowed down my options to Pelican, Jekyll and Hugo. Let’s take a look at each one in turn.

Pelican

As a codenewbie, I liked the idea of Pelican as it uses Python. Python is to me a great language for a beginner. The syntax is really straightforward and easy to comprehend. This was a big plus for. Also, the documentation and quick start are both good for Pelican.

The downsides are the lack of themes. Of course I could develop my own but my focus has to be learning to code and having some kind of qualification and portfolio to show for it. For me, building a theme is someway down the TODO list.

I tried Pelican and managed to get a site up and running, but ran into some technical difficulties trying to switch between templates. My failing I know but this prompted me to try another option.

Jekyll

I plan at some stage to learn some Ruby. Initially I was put off by using something that used a different language but after my experience with Pelican I thought I would try it out.

I took on more than I could manage at this stage. The list of things to install is long, and Xcode itself took ages (4GB download and install took hours - be warned!).

The issue for me was I kept encountering all sorts of problems to install and set-up, from the versions of installed bundler, ruby and rubygems not being compatible, to receiving errors when trying to build the site.

Whilst the community are really helpful, and I hate to quit, I had to admit defeat. I think if you are familiar with Ruby then Jekyll is a really good option. For me at this stage, it was too much of a challenge.

Hugo

I was initially reluctant to try Hugo as again it was a different language from my initial focus list (html and css obviously, javascript and python). What swayed me was my experience with Pelican and Jekyll (primarily due to my lack of programming and technical knowledge it must be said), the good selection of themes available for Hugo, and the excellent user documentation.

With Hugo I had zero difficulties with getting a simple site set-up. The documentation is really good in explaining how to install Hugo and get a site set-up.

I now have the satisfaction of having ‘built’ my own site, can learn more about configuring the site but it is also fairly light touch in maintaining it. (Now as light touch as Wordpress.com or Medium but this is a decision I knowingly took for good reason). I can use it as my blog as part of my journey to learn to code. I also plan to learn more about the Go language, and see how I can use Hugo to build a site.

As an added bonus, it has introduced me to the Go language and I’ve added to my learning list.

Quick Guide to Hugo

This section is intended as a quick reference guide to the key aspects of installing Hugo.

First up, check out these links for really good explanations on installing and setting up Hugo:

Installing Hugo on a Mac
Superb step by step guide to hosting on GitHub Pages

Secondly, here are the key points and commands to consider in order to install and use Hugo:

# To install Hugo via Homebrew
brew install hugo

# Install Pygments for code syntax highlighting
pip install Pygments

# To check if Hugo is installed and display help
hugo help

# Check which version of Hugo is installed
hugo version

# Command to quickly scaffold a new site called exampleName.
hugo new site exampleName

# Hugo runs its own webserver to render the files, includes drafts
hugo server

# Hugo runs its own webserver to render the files, includes drafts
hugo server --buildDrafts

# If a theme is not specified in your config file, add `-t themeName` to the command

# Hugo builds your site into the public folder
hugo

Why I'm blogging again

Sat, 17 Sep 2016 10:15:16 +0000

First, some context. I have blogged before. For several years I blogged on cycling (road, mountain biking, and as a means of simply getting from A to B).

I stopped it in the end because it was very time consuming. Not just the writing but the maintenance of my self-hosted WordPress site.

I vowed when I quit, no more blogging.

So why start again?

My reasons to blog

Learning - to summarise this excellent blogpost, “writing is thinking. There is no more thorough way to understand than to explain in writing.”
Open source - by sharing my learning and technical knowledge to the public (sounds grand, I’m under no illusions I am likely to be the only person who will probably read this) it forces me to really learn, it may help others, and I can start the journey of becoming known in the open source community
Project - building my own site (more on this in another post), I can take on a technical project and learn by doing
Community - again without any illusions of grandeur, if one blogpost helps just one person then I am playing a part in the community of helping others learn to code

About

Mon, 01 Jan 0001 00:00:00 +0000

Hi, I’m Sam. I’m a software engineer.

I live in London, England.

At work, I am a Senior Software Engineer at Otera. Previously, I worked at two other tech start/scale-ups:

After university, I began my career in supply chain working at a logistics provider and then a manufacturer. I then worked for close to ten years at in the Big Four Management Consultancy firms KPMG and EY. I subsequently transitioned to a software engineering career at Big Health.

On this site you can find:

articles: blogs I’ve written
now: about me now and what I’m currently doing

Now

Mon, 01 Jan 0001 00:00:00 +0000

(This is a now page, and if you have your own site, you should make one, too).

Updated on 16th November 2025 at my home in London, UK.

Work

After a couple of years as an Engineering Manager, on the engineer/manager pendulum I’m working on the technical side again as a Senior Software Engineer at Otera.

Exercise

Around a year ago I started going regularly to the gym. I enjoy lifting weights. I have also started going bouldering with my son which is great exercise and a great way to get rid of stress.

Reading

I enjoy reading, mainly sci-fi, thrillers and crime novels. I try to avoid reading too much politics and news as I find it too depressing. I’ve deleted anything with an algorithmic feed from my phone to avoid distractions and doom-scrolling.

Learning

I listen to technical podcasts, my current favourite remains the Changelog. I also read technical software engineering books and articles to learn new things and keep up to date on the latest in software engineering.

Family

I live in London with my family.