Engineering-Process

After reviewing a lot of pull requests, I’ve settled on a simple default: if my comments are all nitpicks, suggestions, questions, or non-blocking issues, I leave them and approve the PR at the same time. Here’s some detail on how it works. But first, two clarifying questions. Why Leave Comments, If Approving? Why leave comments if I’m approving? Comments show that someone has thought about the problem and the solution, and cares about what’s happening to the code. Occasionally, they offer a chance to learn or to surface misunderstandings, assumptions, or hidden risks. ...

If people can make catastrophic mistakes on your team, the process is broken. Real-World Example: Git Branch Protections An example is branch protections in a Git repository. These are rules that prevent engineers from deleting or altering history in shared branches, such as main, which on most teams would lead to a major problem. Engineers don’t intend to delete or alter main, but it can happen when rifling through terminal commands. We’re moving fast, and occasionally we press enter on the wrong command. As a contributor, I expect policies to catch me when I make this mistake. ...

What is a programmer but a series of PRs (pull requests)? I optimize PRs to introduce the best code I can, be easy to review, and document my work so I can make sense of it in the future. Here are some things I always check before opening a PR. Passing Static Analyses All of the static analysis tools in my project must pass locally. On a JavaScript project, that’s an auto-formatter (Prettier), linter (ESLint), and type-checker (TypeScript). All of these run on files I touch automatically. If that’s not feasible for you, a Husky pre-commit hook will do the job. ...

This year I’ve run over 25 Scrum refinement meetings; here’s what I’ve learned. This post will cover: What is refinement, and why does it matter? Two counterarguments, refuted! My step-by-step approach Notes on pointing bugs Let’s dive in. What is Refinement? (Backlog) Refinement is a process of improving tickets so they are understood by the whole team and ready for work. Refinement turns chaff like this: “Design for error on download screen” ...

Confluence was messy. Our documentation felt outdated, hard to navigate, and unreliable. Rather than scrap everything and start over, I decided to try something different: a Kaizen. Here’s what we did, what we learned, and how it went. What is a Kaizen? Kaizen is a Japanese business philosophy that can be translated to mean “Change for the better.” It can be an event, too. Before this experiment, I’d observed a Kaizen workshop once in a factory, but I’d never led one myself, or heard of one done on a software team. ...

Often, when you work as an engineer on a small team, you don’t have dedicated designers on staff. How can you deliver beautiful, intuitive software without designers? Here’s a trick that helps me: decoupling my design work from my engineering work. Clarification: I Love Designers! Let me start by saying: I love designers! An expert designer is one of the most vital people in an engineering organization. I’m not a designer. Great designers are rare, which is why, for much of my career, I haven’t had one. ...

If you’ve ever watched me debug, you might think I’m moving slowly. That’s because I try hard to find every marker on the debugging trail. I believe this is one of the most valuable skills in debugging. What’s a Marker? Let’s say our debugging session is a trail through the forest. ‘O’ is where we are, and ‘X’ is the summit of a mountain. At ‘O’, we know little. At ‘X’, we understand the bug and we’ve fixed it. ...

Reviewing code is tricky. When I’m doing it, I’m trying to achieve a few things at once. In this post, I’d like to document the ways I try to add value via code reviews. My Background & Biases This is the second post I’ve written on this subject; here’s the first. Since 2022, my approach has shifted from strategic to tactical; I don’t prioritize design (the high-level programmatic approach) as much, which I’ll explain in a moment. ...

Have you ever seen a pull request that seems to completely explain itself? It’s a real artifact. I don’t know the project, yet I understand it. How can we get results like this on every pull request, from every developer on the team, every time? The answer is a pull request template. Templates give your team a format that’s detailed, discoverable, and predictable. In this post, I’ll share this technique and why it matters. ...

Here’s some advice about programming I’ve found useful: “Don’t ask for advice; ask for a code review.” In this post, I’d like to explore what I think this adage means. When learning programming, we think there’s a trick to it, that can be solved with advice. If I… …learn the right language, framework, or text editor …attend the best CS program, bootcamp, or workshop …master the ideal learning strategy or morning routine …I’ll have an advantage. In my mentoring of new programmers, many of the questions I answer are about topics like these. I think the answers matter much less than people might think. I stopped giving generalist career advice for a while because I felt like my answers to these questions weren’t helping people. Or that I was communicating my privileges and survivorship bias. ...