Here’s some of the books I read in 2021 that stood out:

Britain Alone - Philip Stephens

Historical account of British foreign policy and geopolitical positioning from Suez to Brexit. Holding ourselves up to the “great power” mirror and seeing a real one reflected in the 40s and early 50s to a quickly diminishing one in the 60s to a former one in the 70s and onwards.

As a historical account kept me hooked. Lots of new detail I didn’t know about Suez, Polaris & Trident, the “Sterling area” and the rollback of Empire.

A large theme (and well trodden elsewhere), is that Britain having not lost the war, sees itself as different and apart from the “lesser countries” of Europe. In the post war period, it still saw itself as one of the “big three” of the US, USSR and Britain/Commonwealth/Empire. Whitehall in the 50s believed the terrible state we found ourselves in post war was merely temporary.

The first half of the book is the slow realisation that it was not temporary, with some fascinating insight into players like Harold Macmillian and the games he played with presidents and parliament. He knew that Britain could no longer act independently from the US and was becoming more economically dependent on the European Community. But post-war British “Great Power” pretensions, from both Labour and Conservative, means we miss out on the first wave of European integration.

Missing that first wave of European integration ends up being crucial to everything that happened next. The UK arrived too late and too poor. The rules of club were set, the direction of travel known. Next up: 40 years of sailing against the wind, demanding opt-outs, rebates.

A self important square peg of an island refusing to bend to the new European destiny that started in Sicily in the 50s, while we were begging the Americans for rockets to shoot nuclear weapons.

Luster - Raven Leilani

Arresting novel about a woman who has a relationship with a married man and becomes part of his family. Big dynamics on race and power. She’s got serious issues which he uses for his benefit, unwittingly or not. His wife is the most interesting character and their friendship is crux of the book.

Side note: made me also think about what a NJ life would have been for Sal and I, had we stayed in New York and moved there. Unrelenting pressure of competitive burbs, living in indentikit, soulless houses in “safe” neighbourhoods. The feeling of guilt if you’re not doing everything all the time compounded if you feel that guilt for your kids. Totally beside the point of the story but nevertheless my personal reaction.

My whiteness and privilege probably means many underlying messages of the book go over my head. Enjoyed it despite that and learned things about being black in America that I had a low level of awareness about but now have a slightly less shallow appreciation of.

The prose is fast! Highly enjoyable to read, reads like a proper new yorker jabbering away at you a million miles per hour. Precise and funny but also sad.

Empire of the sun - JG Ballard

Incredibly moving. Never ready Ballard before so this was an eye opener as the book is quasi autobiographical. It focuses Shanghai before WWII starts in the Pacific. It is under Japanese occupation but the International Quarter is largely respected. The Brits are in control in a very colonial way, with Jim living a life of luxury in amongst a wider Shanghai or total poverty.

This changes suddenly when the Brits and other expats are interned at PoW camp. The story is told through the eyes of Jim, a young frenetic but endearing teenager, who never quite shrugs off childish ideas and questions, much to annoyance of the adults. This keeps him real and hopeful and even idealistic, despite being in a PoW camp.

One of the most interesting threads of the book is how these pompous and over privileged colonial-master type Brits and others find themselves having to live in this new reality where they are reduced to starving, desperate prisoners of war. All the trappings of their life, their power and wealth totally gone.

I think there’s a hugely interesting thread about the seeds of China in the 21st century in this book.

The story of the subjugated local Chinese, who - except for the militias - seem to have to given up on life and resistance and live a pitiful life devoid of any meaning or dignity. No-one, not the Brits or the Japanese value their lives.

There’s a telling line at the end of the book, after the war when Shanghai is back in Allied hands and fully of British and American navy:

However, the heads of the Chinese were already turning to another spectacle. A crowd had gathered below the steps of the Shanghai Club. A group of American and British sailors had emerged through the revolving doors and stood on the top step, arguing with each other and waving drunkenly at the cruiser moored by the Bund. The Chinese watched as they formed a chorus line. Provoked by their curious but silent audience, the sailors began to jeer at the Chinese. At a signal from an older sailor, the men unbuttoned their bell-bottomed trousers and urinated down the steps. Fifty feet below them, the Chinese watched without comment as the arcs of urine formed a foaming stream that ran down to the street. When it reached the pavement the Chinese stepped back, their faces expressionless. Jim glanced at the people around him, the clerks and coolies and peasant women, well aware of what they were thinking. One day China would punish the rest of the world, and take a frightening revenge.

Ballard, J. G.. Empire of the Sun (pp. 278-279). HarperCollins Publishers. Kindle Edition.

This note was orginally written for the Wonderbly dev team in 2017. At the time, the team had about 20 devs, split into three squads, each with a tech lead who was also the line manager. I have since shared it with a few other folks within other companies, who have found it useful. Adding here for posterity.

This document is to help you understand how engineering career progression works at Wonderbly. It explains our principles, roles within engineering and how to make progress.

Defining a linear career progression is not the point of this doc. It’s impossible for a single title to describe you and where you are in your career. There are no accepted industry definitions to follow and what denotes seniority at one company can have mean something very different at another. It’s also perfectly possible for two people with different but equally valuable skills and have the same title.

So therefore the goal of this document is help you understand your next move and provide guidance to your manager to help get you there.

Underlying principles

It’s helpful to have some principles to help us think about titles, careers and progression and the like. These principles reflect our culture, a desire to not constrain people and finally reflect industry experience.

• We’re all engineers - software development is a complex business and requires all kinds of people with different skills and sensibilities to make it a success. Whatever role you fulfill you are first and foremost an engineer, treated on equal terms to all others

• Jobs not titles - we don’t believe titles can act as a label to wholly represent who you are. As much as possible the title should represent the job you do. Statue and authority come by doing

• Grow in any direction - there’s no set path. People and businesses move non-linearly and it’s perfectly possible, even preferable, that career paths do the same.

• Working here is a badge of honour - having Wonderbly on your CV, regardless of your title, should be the best signifier of your talents. To do that we need to strive to make Wonderbly a renowned place to work in London

• Help others first - always prioritise others; helping each other encourages learning for everybody, spreads information and break down silos

Engineering Roles

The following descriptions contain an outline of what we expect to see from each role. This is by no means meant to be exhaustive and instead intending to act as guide for career planning.

The numerical suffixes (eg Engineer II) need not be public - they are there to help you and your manager with career planning to allow you to master the role and ultimately progress.

Describing your title in public

Engineers can specialise in certain areas, such as a specific domain like QA, Infrastructure or Payments, Front-end etc. If you feel it represents you better then feel free to use that specialism can be used in your title, as a prefix.

There’s no need to seek permission to add a prefix to your Engineer title on social profiles, Linkedin etc. Just remember that we’re in a rapidly changing business and industry and the term might become out of date.

Examples:

• Engineer, Front-end
• Engineer, Platform
• Full stack Developer
• QA Engineer

It tends to make less sense to call out specialisms the more senior you are. For Seniors and Principals the focus is at a domain level, so generally there’s always some element of front-end, back-end, infra etc in the role.

Difference between “developer”, “engineer”, “hacker”, “bit twiddler” etc

We make no distinction between those terms. We default to Engineer but refer to yourself with whatever term you feel is more appropriate.

Creating a career plan

A career plan is

• An agreed set of quarterly goals that enable you to exhibit qualities we expect to see of a person in their next role
• Generally the plan is over 6-12 months
• The outcome is a recognition of your personal development (eg title/salary etc), depending on how the goals are met
• Everybody’s plan will be different because we come from different places, but the overall goals are largely the same
• Crafted between you and your line manager

Mastering the Engineer role

The first crucial step in your career is to master the “Engineer” role by incrementally taking on more responsibility by meeting the scopes of level II and III.

Remember the use of numbers, eg “Engineer II”, is a step in your progression towards mastering the Engineer role. It’s not something we expect to put in a contract or callout on social media. Instead it will be used to guide career planning, generally around annual review time.

Remuneration we will reward your progress towards mastery of the Engineering role with your annual raise, decided at your yearly review.

Moving to Senior Engineer

To move to senior you will need to first master the Engineer role (see above).

Then, if your TTL agrees that the opportunity is available within the team, and you are ready, you can work together to create a career plan for a move to senior. This will won’t be easy and we will be looking for you to take on challenges that reflect increasing levels of responsibility and stewardship. A promotion to senior marks an important milestone in your professional development.

Remuneration we will celebrate this promotion with a change in title, a raise to reflect your increased responsibility, rounds of applause and lots of treats.

Moving to TTL or Principal

From senior onwards there are two paths open to you, depending on your interests and needs of the team. You can either grow to take responsibility for a tech team and the engineers in it by becoming the Tech Team Lead. Alternatively you can focus on growing your technical responsibilities by becoming a Principal and help shape our technical strategy.

To move on to either requires the same plan as moving to Senior, except agreed with Head of Engineering.

It’s also perfectly fine to move between roles. People’s situations change as the does the company’s. There’s no defined route that you must take that can never be looked at again. It’s more to do with providing a structure to ask the right questions.

date: 2021-04-01T20:45:15.133Z title: How to write PR descriptions summary: Wonderbly’s guide to the art of creating a good PR

The words below are part of the Wonderbly developer guide. I contributed a little but this is mainly the work of Hraban Luyat and Lev Perlman. They are great devs and I am grateful to have worked with them both.

Pull Requests are about telling a story. What kind of story are you telling? Is it the creation of a new feature, or how a bug has been fixed, or why an improvement needs to be made? Put yourself in the mindset of the reviewer, what does that person need to know to understand your story and be able to do their job.

Remember to balance this with the story told by the source code as a whole. Always judge what the source code will look like after merging your PR, and don’t lose track of its priority over this individual patch.

To help you tell that story, use these these guidelines as much as possible.

Writing a description

First step is creating a useful description. A good description helps your reviewer understand what they are being asked to look at.

The title that says concisely what this PR is

fix: no feedback after editing customisations

Remember: the title has a maximum length of 50 characters. This helps understand the purpose of the PR at a glance when looking at a long list of changes in history view, a typical way of looking at history to see what’s changed:

a10dd93 fix: statement timeout to 300s (#300)
714681a enable heroku nodejs analytics (#299)
12ee117 fix: orderEnricher: removing zip and merging sources correctly (#296)
bebfcf8 feat: stock - upserting stock with permissions (#288)
aa0b34e fix: async nock post request body test in CDS (#293)
ee2df10 feat: Stock Log Levels - change to info (#289)
f6eccc8 feat: psps deps: Passing AppDependencies to all PSPs (#283)
de54de2 docs: improve readme (#286)
8b0d6ec refactor: native request types, no need to redeclare (#284)
8f370fa feat: ecommOrigin in FullPspOrderData (#282)
7272d23 fix: OneFlow: shipping update path (#279)
b791d61 [Stock 403] - handling 403 error from OneFlow stock manager (#278)
5d21f49 Add printForReal boolean to order event log (#269)
050420f feature/ order log formatter (#277)
9e980b4 Fix sample unit test file (#276)

As you can see, some of these descriptions work better than others. Some don’t follow the convention and they immediately stand out; this is why it’s important to follow the convention in all submissions.

Have a good look at this list and evaluate which submissions tell you what you need to know (what changed, which files were touched, …), and which don’t. For those that don’t, imagine having to dig deeper into them and having to manually inspect each one to get a feeling for what actually changed.

As always, with everything you do relating to code: you are telling a story, so keep your audience in mind. What is their perspective, what do they want, who are they? In the case of PR titles, their perspective is this list of summaries. Keep this in mind when writing the title for your own PR.

The description that explains why this PR must exist

Explain why, with a note of what has changed.

When submitting edited customisations for a product after purchasing the user wouldn’t be navigated back to their order. This was broken during the changes made to customisations when trying to fix the case mismatch between Eagle, Website, and Muse. After looking at where the fetch method updateOrderItem was being used I noticed that the actual order response wasn’t being used so I have removed the .then following the call to Eagle.

Again: you are telling a story; who is your audience? It is people reviewing your PR, and people using git blame to see what happened to a specific line, then wishing to see it in the context of its entire patch. What would those different audiences need to know to fully understand the patch? This can include:

• Time pressure (“Should be doing X, but Rob says he wants it done by the end of the day so I must go with Y”).
• Alternative solutions that were not chosen (“Not doing Z because it might clash with Foo”). This is often overlooked but incredibly valuable.
• Links to related issues.
• Links to logs, or copies of logs
• Excerpts from e-mail threads with suppliers / clients
• on and on.

In the end, this is about “what is the context of this patch?” Most of that context could also be put in the code itself, which is more desirable if appropriate (remember the priority: code > patch). It is a delicate balance between what should live in the patch description, and what as a code comment. A rule of thumb is that comments should always go in the code, unless they are only relevant historically, but don’t have any potential to benefit future decisions. If a library was removed because it is unmaintained, it won’t risk being reintroduced, and there is little value commenting on it in the code. However, time pressure from management is almost always more useful as a code comment, because it helps future maintainers understand they can safely rewrite something, that there was no greater purpose to this hack than “getting it out the door.” It is an instance of Chesterton’s fence.

Think about whom this PR will affect

Consider who is impacted by this. Our users? If so, write down how. Is there something our customer support team need to know? How-about dependent systems, is there new behaviour to be aware of? Go through this exercise and you may find new dependencies you haven’t thought of.

Highlight danger

Highlight danger clearly.

• Is there a complication with roll-out beyond a simply deploy? E.g. a new environment variable, a dependent PR etc
• Can this be rolled back quickly? If not, make it clear
• Does this create potentially breaking changes? E.g. a breaking API update

Provide useful links

Link back to the original ticket. Share links so the reviewer can preview.

Overall, don’t make the reviewer work - any link that provides context can be helpful.

Acceptance criteria to show new behaviour

Help someone understand what has changed by adding acceptance criteria. Create a list, ordered in a way that makes sense for the reviewer.

Example:

• Editing a product from /personalized-products/:productSku/preview/:orderId/:itemId (edit in account) will redirect users back to their order
• The user will see their update has been successful on the order page

Include Steps to Test to walk the reviewer through the change

Show the reviewer some steps that demonstrate how acceptance criteria have been met.

For example:

1. Add a product to cart
2. Go through checkout (v1 or v2 doesn’t matter)
3. Once on the order page, click “login to edit order”
4. Click on the edit link in one of the line items
5. You should now be on the preview page
6. Make any change to the product and click save
7. You should now be navigated back to the order page and be able to see the new customisations

Don’t conflate concerns

Reviewers don’t want see changes that aren’t in the description. Adding “oh and I also refactored/cleaned-up a few classes” to the description doesn’t make it ok either.

Imagine being in the head of the reviewer, a PR that does many things (a conflation of concerns) is more change for the reviewer, therefore more things they might miss, therefore more things that may go wrong in production and therefore more time unpicking the changes when it does.

If your code does require a refactor - think whether you can isolate in a separate PR, and start with that. This way, the reviewer might receive several PRs with a smaller amount refactoring prior to receiving the main PR that includes the logical change or the new feature.

Consequently that main PR will be smaller, more isolated, more readable.

Use git to tell a story

This is a hard thing to do but it can make reviewing much easier and when the commits are squashed can provide a decent summary of what happened that we can all see our IDEs.

Writing a good commit message

Borrow this syntax from the Coventional Commits spec: <type>[optional scope]: <description>

Where type is one of fix, feat, or improvement.

Example:

fix: Eagle API: Remove handling of response from edit in account api endpoint

Putting commits together to tell a story

An ideal git log tells a linear story, each commit showing progress to completing the feature. It’s easy to show that progress when you have thought about what you plan to do before you start coding. This will help you, provide clarity to the PR and therefore help the reviewer. Then you can plan the commits as a series of improvements to the PR’s stated goal.

When it comes to review, the reviewer can step through every commit, rather than having to parse every file change all at once.

Provide some tests

Your PR should contain a test that validates the new behaviour. Think from the PR reviewers perspective: tests are documentation, they show new behaviour, what should happen what, importantly, what should not happen.

When writing tests, it’s not enough to prove your code works. Think “how could this go wrong?” and write tests to cover those cases as well. Think how someone could misunderstand or misuse your changes, make sure they are covered in tests as-well.

Add why not what comments to the code

Look at your code and if the reason why is not clear then add a comment, probably with a TODO to remind ourselves that something needs to be done.

If you’re adding comments to explain what this code is doing then stop and think again. This is usually a sign that your code is overly complex. We should be able to determine what the code is doing just by reading it.

Readable code that doesn’t work is better than unreadable code that does work!