When I was twelve and didn't know programming, my dad taught me about binary search. His explanation was so simple that it stuck with me.

I wrote a small interactive book to teach binary search the way he taught me.

The Binary Search Handbook is short and teaches by example.

First, download the book and try it for yourself. It will help illustrate the topics below.

In this post, I'll explain binary search in more detail.

Binary Search Handbook

1.13MB ∙ PDF file

Download

Learn binary search by playing a game with this book.

Download

What is binary search?

Binary search is an efficient algorithm for finding an item's position in a sorted array. It works by dividing the search range in half multiple times.

The array must be sorted for binary search to work.

The search begins in the middle of the array. If the target value matches the middle element, the search ends.

If the target value is less than the middle value, the search moves to the left half.

If the target value is higher than the middle value, the search moves to the right half.

This process continues until it finds the target or nothing is left to search.

Use Cases

Binary search is useful for cases like:

• Checking if a value is in a sorted array: Determine if a specific element exists in a sorted list.

• Finding the first occurrence of a value: Locate the first instance of a target value in a sorted array with or without duplicates.

• Finding the insertion point: Identify the correct index to insert a new element to maintain order.

Finding a word in a dictionary

Finding a word in a dictionary is a great use case for binary search. The Binary Search Handbook illustrates this. A dictionary is a sorted list of words spread across many pages in a book. Let's see how binary search helps find a specific word.

Imagine you have a printed dictionary with thousands of words. Instead of checking each word one by one, binary search lets you find your word in just a few steps.

Subscribe now

Step 1: Start in the Middle

Open your dictionary to the middle page. Let's say the dictionary has 300 pages. Open to page 150. This is your starting point.

Step 2: Ask a Simple Question

Look at the first word on page 150 and ask, "Is the word I'm looking for before this word?" This yes/no question eliminates half of the search results. If the answer is yes, you only have to search the first half. If the answer is no, you only have to search the last half.

Step 3: Halve Your Search

Based on the answer, you either move to the middle of the first half or the second half of the dictionary. If the word is after page 150, go to the middle of the second half, page 225. If it’s before, go to the middle of the first half, page 75.

Repeat Until You Find It

Repeat this process: go to the middle of your current section and ask the same yes/no question. Each time, you cut the number of pages to search in half. This is the power of binary search.

Within a few guesses, you'll have only one page left. This is the page with your word. You can take this further and find the exact line with your word.

First, go to the middle of the page and ask the question. Depending on the answer, your word is on the top or bottom half of the page. Each time, you cut the number of words to search on the page in half. Repeat until there is only one word left.

Why It Works

Binary search is efficient because it reduces the number of pages to check by a large margin. Instead of looking through 300 pages, you can find the page in about 8 steps. That’s because each step narrows down the possibilities by half.

number of steps = log2​(n)

A Fun Example

You can find a word you don't know using the same process. You only need a function to answer the question, "Is it before this?"

You can use this trick to find a word a friend is thinking of in a dictionary without them telling you the word. All they have to do is answer, "Is it before this?"

Big-O

• O(log n) time complexity – Binary search halves the array each time. So, the maximum number of comparisons needed is the logarithm (base 2) of the number of elements.

• O(1) space complexity – Binary search uses the same amount of extra memory regardless of the input array size. It operates in place, only using a few extra variables to keep track of the search range.

Binary Search Tree

Binary search is an algorithm. Its cousin data structure is a Binary Search Tree (BST).

Binary search is great for static, sorted arrays. However, if you insert items into the array, you must resort. Sorting an array is expensive, with an O(n log n) to O(n²) complexity.

A Binary Search Tree fixes this by maintaining elements in sorted order. Each node in a BST has up to two children. The left child contains values less than the parent node. The right child contains values greater than the parent node. This structure ensures searches, inserts, and deletes perform in O(log n) time on average.

When to use Binary Search vs Binary Search Tree

• Static Data (Binary Search): If the data is static (i.e., it doesn't change), a binary search on a sorted array is more efficient. The overhead of creating a BST is usually greater than sorting and searching a static array.

• Dynamic Data (BST): A BST is more efficient for dynamic datasets with frequent inserts or deletes. BSTs provide efficient O(log n) time complexity for operations. This is more efficient than repeatedly sorting an array for binary search.

That’s it.

Binary search is a simple yet powerful algorithm. A code example is at the end of this article.

If you enjoyed the Binary Search Handbook, consider sharing it with someone who might be interested in programming.

Share

What I’m reading

• I often take on more work than I should. and wrote some tips to help with that in How to say "No" and win back your time as a software engineer.

• Don’t Criticise and YOU ARE WRONG! are great contradictory titles from . They’ll both help you correct people without offending them.

• In Glue Work: The Hidden Hero of Team Success, highlights those who work on often-overlooked tasks that hold a team together.

Example code

I've provided an example Python binary search implementation below. This should illustrate how a binary search algorithm works.

Python has efficient built-in functions, such as list.index, to find positions of a value in a list and bisect for binary search operations. You should use those instead of making your own.

This type of algorithm is generally called a “two-pointer”. That’s because it has two pointers, left and right, representing the bounds of the search window.

def binary_search(items: list[int], target: int) -> int:
    # The left and right pointers represent the bounds 
    # of our search window.
    # Initialize them to the entire index range.
    # For example, if the initial list is 
    # [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
    # It starts with left=0, right=9 and looks like this:
    # [>0 1 2 3 4 5 6 7 8 9<]
    left, right = 0, len(items) - 1

    # Continue searching while there is a valid range.
    # The loop stops when left is greater than right,
    # meaning the target is not within the range.
    while left <= right:
        # Calculate the middle index by cutting the
        # current search window in half.
        middle = (left + right) // 2

        # The first time around, left=0, right=9, middle=4
        # [>0 1 2 3(4)5 6 7 8 9<]

        # If the middle element is the target, return its index.
        if items[middle] == target:
            return middle
        # If the target is greater than the middle element,
        # narrow the search range to the right half.
        elif items[middle] < target:
            left = middle + 1
            # The first time around, left=5, right=9, middle=4
            # [ 0 1 2 3(4>5 6 7 8 9<]
        # If the target is less than the middle element,
        # narrow the search range to the left half.
        else:
            right = middle - 1
            # The first time around, left=0, right=3, middle=4
            # [>0 1 2 3<4)5 6 7 8 9]

    # If the target is not found in the array, return -1.
    return -1

assert binary_search([1, 2, 3, 4, 5], 3) == 2
assert binary_search([1, 2, 3, 4, 5], 1) == 0
assert binary_search([1, 2, 3, 4, 5], 5) == 4
assert binary_search([1, 2, 3, 4, 5], 6) == -1
assert binary_search([], 3) == -1
assert binary_search([1], 1) == 0
assert binary_search([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 7) == 6
assert binary_search([1, 2, 3, 4, 5, 6, 7, 8, 9, 10], 2) == 1
assert binary_search([1, 3, 5, 7, 9], 4) == -1

You can read my reply and the lessons on Jordan's High Growth Engineer. I cover the things I noticed software engineers struggle with the most:

• Knowing what to design

• Dealing with unclear requirements

• How much detail to put in a design

From software back to house design

This post is about a concept from software that reshaped my perspective on building design.

I learned about abstraction from software engineering. When I apply the concept to house design, I see many abstractions within houses. In fact, abstractions and standardization are what make modern construction possible.

Abstractions also give us the solution to another challenge with software design: when to stop designing.

When to stop designing relates to how much detail we design. When you've put enough detail, you're done. But how can you reduce the required level of detail to speed up the completion of designs?

Abstractions simplify designs if we:

• Design at boundaries and encapsulate details.

• Get the API right and allow inner details to change during implementation.

• Stop when we've covered all the abstractions.

Abstractions in the home

What abstractions do houses have?

• Doors and windows

• Electrical sockets and light fixtures

• Appliances like stoves and ovens

These abstractions have an expected way of working. There is a standard way to create and use them.

Electricity as a service

We can apply the lessons of how house design uses abstractions back to software design. Take, for example, electrical sockets.

The socket is an interface that provides the service of "electricity." Power delivery to a house has many details:

• Wires

• Breaker boxes

• Power poles

• Distribution nodes

• Power plants

• Fuel

Electrical sockets are interchangeable interfaces. Anything implementing the interface can get power. Thousands of devices work simply because they implement the socket interface and protocol.

As a homeowner, you don't care about these details. You plug a device into the socket, and it runs. You care that outlets are near furniture and have enough power to run everything.

You don't care about any of that as a house designer, either. You only care how an electrical socket functions and serves the homeowner. You know the value it provides, and you describe where to place them.

Abstractions hide complexity

The same is true for software. Users don’t care about the complexity or technology behind it. They don't think about how they're using an abstraction (a UI, a button, an API) or the fundamentals of how it works. They just know that using the interface gives them the desired behavior.

Standards and abstractions make it so you only need to design where to put the socket—not what it is. 

As designers of software or houses, we only need to define abstractions and interactions—not the internal details.

Abstractions are reusable and interchangeable building blocks. They limit the concepts a designer and builder need to know. This complexity-hiding is what makes them perfect for simplifying designs. Designers only need to consider the details that they can't ignore. The builder can figure out and adapt the rest of the details.

When designing software or houses, focus on which abstractions to use and how they interact. Designing the interface is more important than the internal details.

For example, when we describe a new part of a complex system, we do not need to explain how the other parts work. We focus on the new component and treat all the existing components as abstractions.

Say we want to add a Project component. The existing Payments and Database components are abstractions. In the design, we don’t need to know how they work. Only the APIs that support customer requirements are important.

• How will users interact with Projects?

• How will Projects interact with the Database?

• How will users pay for Projects?

The Projects component itself is an abstraction. The API (HTTP port or code interface) is like the electrical socket. The details of how it works within the boundary are irrelevant to the design.

When to stop designing

What's important is describing the interactions at the boundaries:

• Describe interactions between components using API documentation formats like OpenAPI.

• Describe complex order of operations with sequence or flow diagrams.

Those who build it have the flexibility to figure out the inner details.

You only have to design the internals of an abstraction if it is novel. Even then, you only have to design it enough so that the builder understands the interactions.

We stop designing when:

• We've identified all the abstractions.

• Everyone understands how they interact.

There is usually no need to go deeper. The design is good enough to move forward.

But it isn’t finished. As the building progresses, new issues will arise. Update the design with any significant changes as they occur.

What I’m reading

• has a good physics analogy for software: Entropy - Mental Model.

• How to propose an impactful improvement to the codebase and own the implementation by delivers on its title.

• explains Chaos Monkey in How Netflix Uses Chaos Engineering to Create Resilience Systems 🐒

Technology terms evolve over time. Sometimes, the meaning is stuck in the past. Sometimes, not everyone has caught up with the current interpretation. Sometimes, the meaning is mired by misconceptions.

1. Is it a monolith?

2. Are they microservices?

3. Is it serverless?

For each one below, take a look at the diagram and consider the question. Then, consider my take (apologies in advance for the LinkedIn speak). Afterward, I'd appreciate yours in the comments or a Restack.

Is it a monolith?

Is a monolith just a single block of software, or does it extend to the SQL database?

• What if you distribute events?

• What if your UI is served from the same container?

• What if you scale a giant container horizontally to meet demand?

• What if your job workers are instances of the same container as your API?

Is it still a monolith?

Someone told me, "You can’t scale a monolith horizontally. You can only scale it vertically." That seems silly because I’ve scaled huge monoliths across hundreds of small servers.

Whether it’s a monolith has nothing to do with the size of the application or how you scale it.

If multiple applications must always be redeployed together when one changes, they are not microservices. They are parts of a distributed monolith.

Web applications are almost always multi-component systems.

Even the simplest monolith of UI -> web server -> application -> SQL is not a single block of software.

What makes it a monolith?

• Not how many repositories it has.

• Not how many containers it has.

• Not how many lambdas it has.

• Not how many teams it has.

Tight coupling makes it a monolith.

Are they microservices?

Is a microservice completely isolated, or can it share databases?

• What if it's the same database server?

• What if it's the same logical database?

• What if they use different tables?

• What if they use the same table?

Are they still microservices?

Someone told me, "If they share even the same database server, they aren't microservices." That seems silly because running a database server per microservice would be costly and complicated to maintain.

What if you used DynamoDB and had a separate table for each microservice. Are they using the same server? Are they running on the same machine? You don't know and don't care.

Whether it’s a microservice has nothing to do with if they share the same database server.

What matters is how tightly coupled the services are to dependencies, each other, and the data they manage.

If multiple applications own the same data, they are not microservices. If each application owns data isolated from data owned by other services, then they might be microservices.

Databases have different ways of logically separating data, including logical databases, namespaces, and tables.

What makes it a microservice?

• Not how many repositories it has.

• Not how many databases it has.

• Not how many lambdas it has.

• Not how many teams it has.

Loose coupling and high cohesion make it a microservice.

Is it serverless?

Is it serverless because the functions are built and run on demand?

• What if the code runs in containers?

• What if containers are pre-built?

• What if it's microservices?

• What if it's a monolith?

Is it still serverless?

Someone told me, "Only Functions as a Service is serverless." That seems silly because I've used serverless solutions with monoliths, microservices, databases, and machine learning without a single server to worry about.

Whether it’s serverless has nothing to do with if its built on demand or if it uses FaaS like AWS Lambda or Google Cloud Functions.

What matters is that you don't have to manage the servers. That the instances can scale to zero or there are no instances to think about. That it scales up with demand. That you are only billed for what you use.

OpenFaaS uses pre-built containers. AWS Fargate and Google Cloud Run manage and run containers for you. S3 is serverless storage. AWS Aurora is serverless Postgres DB.

Monoliths, microservices, databases, storage, API gateways, event buses, and even complex software like machine learning models can be serverless.

What makes it serverless?

• Not where it's built.

• Not if it uses functions.

• Not if it uses containers.

• Not how many APIs it exposes.

The abstraction of infrastructure management makes it serverless.

(Because "serverless" was originally associated with FaaS, people are now using "Serverless Functions" and "Serverless Containers" to distinguish the type of serverless architecture.)

("serverless" actually goes back much further. It originally, originally meant "only clients" as in peer-to-peer. That all changed in 2014 at re:Invent when Amazon announced Lamba)

Next actions

What are your thoughts?

I originally posted these on LinkedIn. They sparked some interesting discussions.

• Is it a monolith?

• Are they microservices?

• Is it serverless?

• Bonus: Microservices are not Apps?

Subscribe now

We will never have enough information before implementation to be able to design a perfect solution. Inevitably, what we know will change as we implement.

We learn from the implementation done so far. Outside factors change requirements, schedules, or resources. A detailed design is too rigid to allow the team to adapt to changes.

Too much up-front design-decision slows projects down. It limits the flexibility of the people implementing it. I prefer lightweight design processes that enable autonomy. We want just enough information for stakeholders to move forward.

We don't need a perfect solution — only a good enough one.
We don't need a detailed solution — only just enough of one.

A solution direction is better than a solution destination. If the team understands the problem, they can pivot as much as needed to deliver a good enough solution. So, providing just enough context is crucial to enabling autonomy. Leave the details for later — for the last responsible moment.

So then, what is just enough context? Let's dig into the details.

Why do we need a design document anyway?

A Design Document describes the context of a problem, the outcome expectations, and the solution to address it.

Its purpose is to:

• Get alignment on business needs.

• Provide a solution that will satisfy those needs.

• Inform those impacted.

• Guide those who will implement it.

It is the rallying point for all technical discussions around a problem.

It should only be extensive enough to meet the team's needs — no more, no less.

Who figures out all this context?

The engineers close to the problem drive the design — they are the "Driver". Not product. Not architects. Everyone supports and collaborates with the Driver.

In DACI terms, the Driver is the person who moves the project forward and is responsible for the decision-making process. (For more on what it means to be the Driver, see Driving software design forward)

So, the Driver figures out the context.

Who is all this context for?

The goal is that you can hand the document to anyone with the required experience on your team, and they can implement the solution without your further input.

The more context you can provide, the better they will understand the problem and how your solution addresses it. The more they understand the problem, the more capable they'll be of adapting the solution direction to changing demands.

Who needs this context depends on the particular problem that a solution is being designed for. Depending on the scope of the problem, the audience can include:

• Product team

• Security, Privacy, or Compliance teams

• Architects

• Engineering managers

• Operations, Platform, or Infrastructure teams

• Quality Assurance

• Implementing engineers

You are writing for the audience. Consider who your audience is when designing. Anticipate the audience's questions and answer them in the document before they have to ask. Make it easy for them to see that you understand the problem and that your solution addresses it.

Yes, but how much context is that?

Keep in mind that readers have a limited context window. For designs, the context window is everything they know about the products within the organization. Everyone's context window overlaps with each other's at different points. You can only address so much context, so your document itself has a limited context window.

The document's context window is a sliding window that falls somewhere between high-level business information and low-level implementation details.

Put the most relevant and urgent information in the design context. Then, go a step further and widen the window slightly to the left to give engineers hints of where to go for more business information. Much of the document will go into implementation details, so there is usually no need to widen the context window further to the right.

One way to provide additional context, especially if you're feeling lazy efficient, is to provide links. Everyone can use the links as a breadcrumb to find more relevance. The links also bind related information together through backlinks. Future developers, including future you, will thank you for these links.

Isn't that a lot of work?

The challenge is to figure out what information will drive the design in a good direction and well inform the people implementing it.

All this might sound like I suggest you design every function call and write pseudo code. I am emphatically not. The document should stay high-level and leave low-level implementation details up to the team who will implement it.

Convey just enough context so the people implementing it understand enough to have autonomy. Then, they can make micro-decisions while satisfying the organization's needs.

The amount of context you need to provide is proportional to the complexity and impact of the problem you are solving.

• More complexity = more context

• Involves multiple internal teams = more context

• Huge impact on customers = more context

• Affects many services = more context

If you are designing a simple solution to a problem that only affects your team, then the context and document should be relatively small.

If you are designing something that affects a lot of teams or has a huge business impact, then you will need to provide enough context to inform those affected and convey that impact.

What context is valuable?

• Current state and how it falls short of the business need

• Problem description, particularly user or business pain points

• Why this change needs doing from a business perspective

• Level 1 or 2 C4 Model diagrams

• Use cases that explain goals a user should achieve using the system

You might notice an emphasis on "business." Business impact is the most crucial consideration of a design. If it does not satisfy the needs of the business, what is the point? 

If someone can't convey business needs and impact or they are not well understood, the design's fitness can not be judged. If it can't be judged fit, the design, its context, or the project should be reconsidered.

Understanding the business needs and the impact of a change is a key motivator and grantor of autonomy for the team. It enables them to take pride in ownership.

With enough context, the team can make sound decisions when adapting to changing demands.

For more details on design, see:

• Autonomy for Software Architecture Design

• Architecture Principles streamline development

Since then, I’ve gained many new subscribers and many times more followers on LinkedIn. In the last 3 months, 1000+ people have subscribed to Dev Details.

That means many of you are recent subscribers who probably haven’t seen my earlier posts. I’ve included a few below to highlight my past content.

Thank you for reading Dev Details. It would mean a great deal to me if you shared my posts with software engineers you think will appreciate them.

Share

Writing is thinking. It helps me to formulate my ideas more clearly and share them with everyone. Each time I write, I get better at it and the topic I’m writing about. I encourage any software engineer who wants to expand their engineering skills to start writing publicly.

I write a lot as part of my role as a software architect. But do I still code? I answer that in the post below.

Early Posts

Popular posts

Dev Details

A practical example of using AI for coding

ChatGPT and other LLMs have impressive coding capabilities. However, the obvious way to use it is like driving a race car on square wheels — inefficient, teeth-rattling, and headache-inducing. I've developed some techniques for working with AI coding tools that get good results. Here, I'll focus on how you can add generative AI to your workflow…

Read more

3 years ago · 5 likes · 1 comment · Mike

Dev Details

Algorithms in interviews suck. Cut it out.

Modern software development is a spectrum ranging from deep algorithmic work to system design. The majority of software development happens between that range. Most developers work on application development, which is closer to system design than it is to low-level algorithms…

Read more

3 years ago · 11 likes · Mike

Dev Details

Driving software design forward

In order to scale, Architects should not design. They should facilitate the software architecture process. This is how to scale and enable autonomy. But then, who should design? Effectively, all engineers. Junior Engineers design for small problems that only impact things the team owns…

Read more

3 years ago · 5 likes · Mike

Subscribe now

While they're mostly joking, there is a kernel of truth and a lesson in them. I want people to think, "If I shouldn't do this, what should I do?".

I end every post with:

Follow me for more career-ending 🛑 advice on Fridays and hit that 🛎️

Not everyone reads to the end before getting outraged at how stupid I must be to believe what I say.

The disturbing part is that the more ridiculous I make the posts, the more people think I'm serious.

Based on the reactions, this means there are people who think my career-ending advice is reasonable and not career-ending at all.

Reactions

From the LinkedIn reactions, it's hard to say what people think. The thing is, I can't tell if I myself am falling to Poe's Law.

Without a winking smiley or other blatant display of humor, it is utterly impossible to parody a {topic} in such a way that someone won't mistake for the genuine article.

Here's how I can interpret the reactions:

• 😂 Funny: They get the joke and think it's funny.

• 👍 Like: Default reaction, so it can be a mix of people who understand the joke, people who click like on all my posts, and people who do not understand it's a joke and genuinely think it's good advice.

• ❤️ Love: Do they love the joke or love the advice?

• 💡Insightful: Seriously? What am I supposed to think here? You must be messing with me!

• 👏 Celebrate: 🤯

• 🫶 Support: Does this mean, "Nice try, better luck next time?"

I know some of the non-funny reactions are to troll me. (Looking at you Dariusz Sadowski). Now that I've pointed this out, I'm sure to get even less useful data as more people troll by giving non-funny reactions to my post.

(BTW, if you want to troll me by clicking random reactions on all my old posts that you haven't read yet, I support that 🫶.)

Diagram

To illustrate the point, here's a graph. Impressions and engagement are trending up, so my content is getting more attention over time. Presumably, this means it’s better. However, the Funny reaction percentage is trending down. It either means more people are taking this seriously and using non-Funny reactions, or it’s large-scale trolling.

Full stats of posts since the beginning

Career-ending Advice

Anyway, enough about my confusion. Here’s all the career-ending advice from latest to the beginning.

When building out new features, how do you balance speed of delivery with implementing higher quality yet more time-consuming code?

At a high level, such as when designing, I try to design/envision what the end goal would look like. I think several iterations down the line. Then, I work backward from that design to figure out milestones that will get me there.

Since I know where I intend to go, I can take shortcuts. But I’m not taking blind shortcuts. I know what tradeoffs I’m making — what it will save in time now vs. cost in tech debt later.

At a low level, I optimize for speed of delivery by writing tests that validate behavior interwoven with writing code.

I'm cheating with my answer here because if you write good tests, higher-quality code naturally follows.

Starting with a test and refining it while you code allows you to develop and deliver faster. Everything else to speed up delivery or improve code quality is secondary. If you have no tests or bad tests, you will become slower and slower each time you deliver.

OMG is this really a post about TDD??

Not entirely. But I’ll need to explain the reasoning behind the answer to the original question.

Many people have a negative reaction to Test-Driven Development (TDD). Some might say, "If you don't like it, you're doing it wrong". Instead, let me explain a little about how I develop, and then you can see if it resonates.

Kent Beck is well-known for TDD. His writings on the matter are much better than mine. He's been writing about his next book on his Substack Software Design: Tidy First?. You should check it out.

I'll give a pragmatic view of how I write tests as an integral part of coding. But first, what is a good test?

What is a good test?

If you're writing tests with the goal of reaching some coverage metric or because the CI gods demand it, you will fail. The goal of a test is to verify behavior — not simply exercise code.

When people think "testing", they usually think "unit tests". I don't think we need unit tests as they're commonly defined for the most part:

A unit test is a way of testing a unit - the smallest piece of code that can be logically isolated in a system.

A small piece of logically isolated code rarely does enough to be considered a useful behavior. (The exception here would be something like a low-level library. In that case, the code is generally small and logically isolated, and the user is someone who uses this library.)

Focus on testing behaviors — not code units.

Behavior testing seems to be the key mind shift that people overlook. Many people get caught up with TDD because they're thinking unit tests. Writing unit tests first — for everything — will result in way too many tests, too much noise, and not enough signal. It will bind your tests to the implementation. That way is the fast track to codebases no one wants to work on. You will hate it. This says more about approaches to excessive unit testing than it does about TDD.

Good tests are from the point of view of the caller (of the API, of the function, end user, etc.), and they verify a desired behavior.

This is the basics of Behavior-Driven Development (BDD).

Fewer unit tests; more tests of behaviors.

Behavioral tests may result in a single test covering a large area of code when a lot of code is necessary to enact a behavior. This is okay. This is desirable (a topic for another day). It usually leads to more functional and integration testing and very little unit testing. (Aside: This doesn't mean use mocks — excessive mocking is an anti-pattern. Look at testing analogs or just run the dependency, e.g. SQL, on a RAM-disk instead.)

So...

A good test is a test that verifies behavior.

Writing tests as an integral part of coding

It seems many people think test-driven development means "write the entire test first." Sometimes, they think it means "write all the tests first." The immediate follow-up to this is, "I don't know what code I'm going to write, so I don't know how to write the entire test first." Another common argument is that "TDD works when you know what you're going to build but not when you're doing a proof of concept."

These points are emphatically incorrect.

With TDD, you write a test intermingled with writing the implementation. It is what helps you figure out what the code will do. So, it works even better when you have no idea what you want the code to do.

The basics of TDD (Red; Green; Refactor):

1. Write a test that does the behavior you're thinking of. It should fail when you run it.

2. Write a minimal implementation to make that test pass.

3. Consider improvements to your implementation. If there are none, go to step 1 for the next behavior.

Consider this experiment: Do not run the UI while writing server code. How would you verify your server code is working? (Aside: I never run the UI when I write server code.)

You could use something like curl, Postman, or another API client.

The tests are my user/my API consumer/my Postman — except I can run them repeatedly on-demand.

I write a test that does one simple API call. Maybe just a GET /api/ping. It will fail.

I add server boilerplate and the implementation for ping, so now I have a repeatable API server setup.

Then I think, “Okay, what does this API need to do?” So, I write an experiment in code. I write a new test to POST /api/thing.

Half the time, I write what I expect the response to be. Half the time, I don't even bother to anticipate the expected result.

I do something like assert response == {} in my test, which will fail when I add a body. I then do a minimal implementation and design what I want the body to return as I write the code. Then, I go back to the test, run it, visually inspect the response, and copy/paste it as the expected response.

Note that Kent Beck considers this practice to be a TDD mistake. I agree in principle, but practical need (developer laziness efficiency) often outweighs the value of principle. Handwriting an expected JSON response can be tedious. 😂

Mistake: copying actual, computed values & pasting them into the expected values of the test. That defeats double checking, which creates much of the validation value of TDD.

With unknown or vague requirements, I'm discovering the requirements and the implementation simultaneously. I'm designing the user interaction and the implementation at the same time.

The tests are my requirement assumptions and the user interface. I'm not trying to cover all cases, only the ones I want the user to perform and the error states I expect.

How does writing tests like this help me deliver faster?

As long as the tests cover the business use cases — the behavior, you can write whatever fast/hacky code you need to.

The tests ensure the behavior is correct. When you have time (this is a fallacy: later == never — there is never time to refactor until you are forced to 😅), you can refactor the implementation safely because the tests ensure you keep the correct behavior.

To deliver faster, we can take deliberate shortcuts to get something done faster. We agree to take on tech debt that we will pay down later. This might involve writing code that will be completely thrown away or using less-than-ideal technologies in the beginning.

For the “throw-away code” aspect, this is also where tests shine. If you don’t write tests, you’re hesitant to throw away code because it’s working, and you might not actually know how it works.

So, instead of throwing away the old implementation (and keeping the tests) — which would allow you to write better faster — you keep tinkering on the old code until it is a spaghetti mess.

“throw-away code” should actually be thrown away. A new implementation should be written using what you learned from the experimental code with the tests as the driver.

Managing risk to deliver quickly with high-quality

All code has tech debt. Accepting that tech debt is a reality and making deliberate decisions about when and where to take it on is risk management. Ignoring tech debt or blindly coding without acknowledging it exists means the tech debt is in control and decides when and where to present itself.

It’s more about deciding where to put the debt — where I’m willing to take on the risk of debt.

Once it comes time to code, here is the order I think it is important to get things “right”. The later the stage, the less risk when accepting tech debt.

1. The tests — capture the business use cases and behavior.

   • Tech debt here is problematic because if you can’t write the test, you don’t understand the feature.

   • If you don’t understand the feature, you have no idea what tech debt and risks are involved.

   • It is always harder to add tests after the feature is complete because you must first figure out how it was implemented and then write tests around it — warts and all.

2. The public interface — A minimal interface that provides the operations needed by the business use cases.

   • Writing this with the tests helps you design a minimal interface.

   • You write what is needed by the business use cases instead of what might be needed.

   • The interface is hard to change once it is public — especially if we’re talking about a library or API.

   • Once in the wild, you must support that interface or force people to stop using it.

   • The smaller you make the interface, the less you have to support, which reduces tech debt.

3. The implementation — This is where it is easiest to accept tech debt.

   • Since the tests describe how it should work, and the interface is what your users are using, you can change this as much as you like, freely.

   • This includes complete rewrites and changing technologies (databases, event-based vs. HTTP, etc.).

Essentially, leave the details to the end. Tests drive the interface. The interface is essential, but not a detail. Whether it uses MySQL vs. PostgreSQL, or HTTP vs. events, or threads vs. blocking, etc. are details. The longer you wait to fill in the details, the more flexibility you have.

Good tests mean you can change the details with ease later — even if you already wrote a working implementation.

Conclusion

To balance speed of delivery with delivering higher quality, write implementation intermingled with writing the test in a cycle.

It's the easiest way to manage risk so you can deliver code faster.

To manage risk, get things "right" in this order:

1. Tests

2. Public interface

3. Implementation

Subscribe now

Working remotely is great, and getting to occasionally meet in person with people grows relationships that make remote interactions smoother. For these in-person meetings, I focus on sharing ideas and meeting people rather than making decisions. We can discuss topics as a vehicle for getting to know one another and then handle the process of actually making the decision remotely.

I did have a mishap one night, though. What do you do when the ceiling in your hotel bathroom starts leaking at 1 AM?

Roundup

I typically write rather detailed posts about various architectural topics that come up during the course of my work. The newsletter is called “Dev Details”, after all. I’ll write a long, detailed article on a particular topic and then do some short posts on LinkedIn related to that main topic. This is a summary of those posts for the week.

Design Patterns

I pointed out that: Singleton is the most design pattern. There were many helpful and not-so-helpful comments on why it’s the most design pattern.

Career Advice

On Fridays, I give (bad) career advice. There is real advice here though. Basically do the opposite of what I suggest.

SQL

I asked, what does SQL sound like? Your thoughts?

Microservices

Some advice on tools in your tool belt. Sometimes you don’t have enough.

Artificial Intelligence

I want AI to be better at generating code. Maybe ChatGPT will scrape this and be encouraged.

Architecture Principles

The deep dive Dev Details article for this week was on how Architecture Principles streamline development. Here is the LinkedIn post:

Architecture teams can shift culture, streamline development, and increase quality without being an ivory tower

How? One tool is Architecture Principles.

Architectural principles streamline the development process by setting clear guidelines and standards.

However, they only do so if everyone, from top to bottom, is aligned on those principles.

🔹 What's that you say; your company has no Architectural Principles?

It might not be easy to see them. But they’re there, affecting every decision.

🔸 Each developer has their own set of architectural principles.
🔸 Each team implicitly has them based on the collection of developers and past implementations.
🔸 Engineering leaders have them whether they're technical or not.
🔸 The CTO and CEO have them.

The problem arises when everyone has architectural principles but does not know what everyone else's is.

One of the topics we discussed was Architecture Principles, so I wrote about how Architecture Principles streamline development. One of my favorites is

Interview

I did an interview with . Want to know what it’s like to be a Software Architect? Read this interview where he asks me about my approach to Software Architecture, how I got started with it, and how others might follow the same path.

Engineering Leadership

Growing from engineer to architect and thriving

Intro This article is the next edition of “Which is the right engineering career path for you?”. This edition is particularly made for engineers to make good decisions regarding their career growth. Knowing in which direction to grow, will ensure you focus on learning the right things…

Read more

3 years ago · 25 likes · 6 comments · Gregor Ojstersek

Next Steps

If you enjoyed the content, repost or forward to someone else that might enjoy it.

If you’re not already, follow me on LinkedIn for more short form content.

Subscribe now

I use Architecture Principles to make positive cultural shifts, simplify development processes, and increase the quality of the software delivered. Continue reading to learn how I introduce, choose, and use them.

Awareness

Whether you're aware or not, your company, whether they are aware or not, is already using architectural principles.

What's that you say; your company has no architectural principles?

It might not be easy to see them. But they guide big system-wide decisions as well as small, every day, one-line-of-code-at-a-time decisions.

Each developer has their own set of architectural principles they work with. Each team implicitly has them based on the collection of developers and past implementations. Engineering leaders have them whether they're technical or not. The CTO and CEO have them.

The problem arises when everyone has architectural principles but does not know what everyone else's is. Software development suffers when everyone is not aligned on Architecture Principles.

Okay, everyone has architectural principles, so what?

For developers, architectural principles offer clear direction and a framework for decision-making. They foster a culture of autonomy, allowing teams to make decisions and develop solutions independently, free from constant oversight or approval from a central authority. This independence empowers teams to innovate, iterate, and quickly adapt to changing requirements.

For businesses, architectural principles clarify the business's technical goals. This reduces technical debt by promoting consistent, scalable, and maintainable software. That leads to robust, adaptable systems that make change easy. Which, in effect, increases market responsiveness and competitive edge. They foster a culture of quality, enhancing customer trust and satisfaction.

For customers, architectural principles may not be directly visible, but their impact is evident in the quality, reliability, and user experience. Good principles guide the creation of software systems that are secure, scalable, and have a user-centric design. Ultimately, the principles contribute to the timely delivery of features and solutions that meet customer needs and expectations.

Alignment of architectural principles is critical to achieving these positive effects. They define the boundaries and guidelines within which teams should work while still granting them the freedom to innovate and make independent decisions. By adhering to these principles, teams can align their designs with the organization's overall objectives.

When are the principles used?

I prefer design processes that do not require central approval. Architecture Principles are a key component that enables autonomy in software development. Whenever a member of the team has a decision to make or a design to create, they reference the Architecture Principles for guidance. When the team adheres to the principles, their decisions will align with business and architectural goals.

During the review of a design for fitness to a solution, the team verifies it adheres to the principles. Concerns can be raised by anyone on the team, including Engineers, Architects, QA, Product Managers, etc.

For the design processes I champion, if a design adheres to Architecture Principles and uses only technology from a Tech Menu/Radar, then the team is empowered to self-approve the designs. My goal is to minimize oversight and give teams the autonomy to make their own decisions.

However, sometimes there is a legitimate reason to ignore or go against an Architecture Principle. In that case, autonomy can't be maintained, and the decision must be approved by a higher authority. This is typically done by an Architecture Advisory Forum (AAF), Architecture Board, Engineering Leaders, etc.

What do Architecture Principles look like?

Architecture Principles typically address various aspects, ranging from system security, performance, and scalability to coding standards, data management, and user experience.

A few common principles are:

1. API First: Treat APIs as a user-facing and critical part of the product. Design APIs first -- before implementation -- to ensure they meet a user need, are interoperable, and ease integration.

2. Don't Reinvent: Avoid "Not Invented Here" Syndrome by preferring to use existing products, services, and libraries instead of developing them in-house. Buy -- not build.

3. User-Centric: Focus on end-user needs, preferences, and feedback in design and development. Endeavor to understand why a user needs a solution and how that solution serves the user's needs.

Dev Details

Architecture Principle Examples

Below are over 25 examples for inspiring your Architecture Principles. Expand upon them to fit your specific use cases, drive your culture, and remove ambiguity. Independently Deployable: Modular Software, Modular Teams. Isolate software and team development to increase flexibility and robustness. This approach promotes efficiency, maintainability, and adaptability…

Read more

3 years ago · Mike

What makes a good principle?

Principles should be SMART (Specific, Measurable, Achievable, Realistic, and Testable).

First, let's consider a principle that is not SMART: Zero Bugs.

• Specific: Unclear what defines a "bug" universally.

• Measurable: Proving zero bugs across scenarios is nearly impossible.

• Achievable: Reaching zero bugs is unrealistic due to complexity.

• Relevant: Aiming for zero bugs may divert crucial resources.

• Testable: Testing for the absence of all bugs is virtually impossible.

Let's see how the example principles are SMART.

API First

• Specific: Design APIs before implementation for a user need and make them public.

• Measurable: Quality of integration, interoperability, and documentation can be assessed.

• Achievable: Can be implemented with proper planning and design.

• Realistic: Within the capability of most development teams.

• Testable: CI can enforce that API specifications are present and covered with automated tests.

Don't Reinvent

• Specific: Use existing solutions over in-house development.

• Measurable: Time and cost savings can be evaluated.

• Achievable: Solutions can be found in commercial or open-source products and services.

• Realistic: Aligns with the capabilities and resources of the team.

• Testable: The value between buying and building can be clearly assessed.

User-Centric

• Specific: Designing based on end-user needs and preferences.

• Measurable: Customer satisfaction and user experience can be quantified.

• Achievable: Can be implemented through research and user feedback.

• Realistic: Possible with the right mindset and team focus.

• Testable: User satisfaction and experience can be tested.

How do I choose Architecture Principles?

There are a few ground rules I set for choosing principles:

1. They must align with business goals.

2. They must be sourced from the teams.

3. All teams must accept and actively support them.

Principles should be tightly aligned with the organization's goals, vision, and mission. Good principles positively influence the behavior and culture of the team. They should inspire and guide without stifling innovation or being too rigid.

To help align principles to business goals, first, define the business goals. If you’ve already done that, then great, make them available to everyone. If the business goals aren’t clearly defined, that’s another topic, but start with acute problems the business is facing. Are you trying to grow the user base, increase customer satisfaction, improve reliability, improve quality, etc?

How many principles you need largely depends on your goals. I typically start with 6 principles to address acute issues. As your needs grow in complexity and variety, add principles to address them. Companies tend to end up with around a dozen. You’ll want to evaluate principles regularly, every six months or so, and remove ones that are no longer providing value.

How do I source principles from the team?

You’ll need to get alignment and buy-in across the organization, but you have to start somewhere. I like to start with a small group of representatives from every team to draft the initial 6 principles. Then run through a roll-out strategy with checkpoints to get alignment amongst all the teams.

A typical process that I use:

1. Assemble Architects, Principal Engineers, and engineering leaders for a brainstorming session.

2. Use DACI: Elect an Architect or leader to Drive this exercise. The engineering group will be Approvers by voting (see below). Everyone is by nature a Collaborator, and other people (such as Product) may be consulted. The entire engineering organization will be Informed.

3. Have each member pre-read this article (possibly with a silent meeting).

4. Lay out the business goals.

5. Review example principles.

6. Put the example principles in a spreadsheet as a starting point. Only put principles that you can reasonably align with business goals.

7. Have everyone raise additional principles for consideration. Whoever raises a principle should explain how it’s applicable, aligned with business goals, and SMART.

8. Each member only gets half the votes for the number of principles we want. So, in this case, everyone gets 3 votes.

9. Add a column to the spreadsheet for each member.

10. Each member will put a ranking, 1, 2, or 3, alongside up to 3 principles.

11. Tally the totals for each principle.

12. Take the top-voted half (in this case 3) of principles and automatically “ratify” them.

13. Discuss and debate the remaining top-voted principles to see what else belongs on the list of 6.

14. The Driver will refine the principles and record the results.

15. The Driver will create one Any Decision Record (ADR) per principle.

16. At this point, you might be satisfied approving the ADRs but hold off so you can get feedback from the rollout process. An Architecture Advisory Forum (AAF) could be used, but this group likely is the same group as the AAF.

17. The Driver will start the rollout process.

What is the rollout process?

“Geez, it’s like you have a process for everything,” you might say. Well, yes, everything has a process, whether we explicitly state it or not. I like to make processes explicit so everyone understands where we are and what to expect next.

If you have a small team and everyone was well-represented during the selection process above, you’re done! Approve the ADRs, and inform anyone who missed out. Don’t worry; principles are reversible by design, so don’t fret about being too hasty with the approve button.

However, if you have a large team, which you likely do because you weren’t already aligned on principles, then a roll-out strategy is needed to get alignment. Alignment is required. If your teams don’t believe in and agree with the principles you’ve chosen, they will not use them, and they will have false autonomy.

Here’s the rollout strategy I’ve used:

1. Start with getting alignment with Staff+ Engineers. The Principal Engineers will drive this, with the support of the architecture team.

2. Give the Staff+ Engineers this article as pre-reading material.

3. Call a meeting to discuss the principles you’re considering adopting. Make it clear you want feedback before moving forward.

4. Discuss each principle you’ve chosen and, most importantly, why you chose it and how it meets business needs.

5. Discuss some of the other principles you considered and why you didn’t ultimately choose them.

6. Ask for feedback. Are there any other principles you should have considered? Were the assumptions of why the principles were chosen wrong? Are any principles in actuality untenable?

7. If there is no alignment, refine the principles and repeat. This might involve going back to choosing different principles. If so, there are likely some larger communication problems between engineering leadership and individual contributors to address. If there is alignment, move forward.

8. Have the Staff+ Engineers repeat this exercise with the rest of their team. Their resident Principal Engineer or Architect can sit in for support. If any revisions are needed, the Principal Engineer should drive it.

9. This should result in all engineering teams having a chance to collaborate and provide enough feedback for the Architects, Principal Engineers, and engineering leadership to approve.

10. Approve the ADRs.

11. Inform the rest of the company about the decisions, especially close partners like Product, User Experiences, Customer Support, QA, etc.

What's next?

• Learn more about autonomy in software development.

• Check out these example principles as inspiration for your own.

• Use your chosen Architecture Principles for guidance in your day-to-day work.

• Evaluate your principles a couple of times a year, keep what's providing value, drop what's no longer useful, and add what's needed.

Related Reading

• Art of Scalability discusses Architecture Principles in greater detail.

• Independently Deployable: Modular Software, Modular Teams. Isolate software between teams to increase flexibility and robustness. This approach promotes efficiency, maintainability, and adaptability.

• Pit of Success: Make it easy to do the right thing and hard to do the wrong thing. Design intuitively to guide users and developers towards success, making correct paths easy and mistakes difficult.

• Contribute to Open Source: Foster community collaboration, promote knowledge sharing, improve software quality, and give back.

• Deploy Continuously: Emphasize regular, automated testing and deployment to enhance rapid iteration, resilience, and adaptability.

• Enable Local Development: Use practices and patterns that allow components to be developed and run in local development environments.

• API First: Treat APIs as a user-facing and critical part of the product. Design APIs first -- before implementation -- to ensure they meet a user need, are interoperable, and ease integration.

• Test First: Write tests before code to clarify requirements, prevent defects early, and maintain code more easily.

• User-Centric: Focus on end-user needs, preferences, and feedback in design and development. Endeavor to understand why a user needs a solution and how that solution serves the user's needs.

• Don't Reinvent: Avoid "Not Invented Here" Syndrome by preferring to use existing products, services, and libraries instead of developing them in-house. Utilize existing solutions to save time and resources, focusing on unique value propositions. Buy -- not build.

• You Build It, You Get the Alert: Put ownership of observability, monitoring, and the resulting alerts on the team that codes it. This ties responsibility to creators, encouraging careful development and a culture of accountability and responsiveness.

• Graceful Degradation: Design the system to continue functioning even when some components fail, providing a lower-quality service instead of total failure.

• Integrate Continuously: Automate the build and integration process, and use trunk-based development to enable frequent merges, ensuring that code changes are consistently tested and integrated into the shared repository.

• Security by Design: Embed security considerations from the outset, including authorization, authentication, and encryption to protect data integrity and privacy.

• Security by Depth: Implement multiple security controls throughout the system, layering protections at various levels such as network, host, application, and data, to enhance overall security and ensure that breaching one layer doesn't provide access to others.

• Reactive Design: Build systems that respond gracefully to change, whether in load, user behavior, or underlying subsystem behavior.

• Emphasize Interoperability: Focus on creating interfaces and components that can work seamlessly with various systems, promoting flexibility and adaptability.

• Environment Agnosticism: Design the system to run across various environments and platforms, reducing dependencies on specific technologies or vendors.

• Immutable Infrastructure: Once deployed, components are never modified. Use infrastructure as code and recreate components instead of modifying them, ensuring consistency and reducing potential discrepancies across environments.

These principles come from Art of Scalability:

• N + 1 Design: Ensure that there is at least one additional instance of a system to handle failures. It's about building redundancy for reliability, and follows the rule of three: one for you, one for the customer, and one to fail.

• Design for Rollback: Create systems that are backward compatible so that changes can be rolled back if problems arise. It's about being able to revert to a previous state if a failure or issue occurs after an update.

• Design to Be Disabled: Create systems with the ability for parts of it to be disabled, especially in risky components. This enables more time to fix issues without the system going down. One way to do this is with feature flags.

• Design to Be Monitored: Build systems that are self-diagnosing. This involves monitoring and logging the right information so that scalability issues can be addressed earlier.

• Design for Multiple Live Sites: Plan for having multiple geographically dispersed data centers from the design phase. This allows for rapid deployment and helps in ensuring continuity during geographically isolated disasters.

• Use Mature Technologies: Employ proven and reliable technology when high availability is required. New technologies may offer competitive advantages but can also introduce more risk.

• Asynchronous Design: Design systems to act asynchronously instead of synchronously. Asynchronous systems are more tolerant of slowdowns and do not block the entire chain, enhancing scalability.

• Stateless Systems: Avoid maintaining information about previous operations (state) as it can cost money, processing power, availability, and scalability. Designing stateless systems whenever possible simplifies scaling and enhances flexibility.

• Scale Out, Not Up: Focus on horizontal scaling (adding more systems) instead of vertical scaling (upgrading a single system). It facilitates near-infinite scaling and is essential to leveraging the elasticity and auto-scaling features of modern infrastructure.

• Design for at Least Two Axes of Scale: Think ahead to ensure systems are scalable, considering both present and future needs. Implement strategies like horizontal splits and customer segmentation to accommodate growth.

• Buy When Non-Core: Focus on core competencies and purchase non-core components. Building should only occur if it creates a significant difference in the product or platform, enhancing competitive differentiation and shareholder value.

• Use Commodity Hardware: Opt for cheaper, commodity hardware if it can scale horizontally and if the cost of ownership, even with higher failure rates, is lower than using higher-end hardware.

• Build Small, Release Small, Fail Fast: Emphasize small, iterative development to minimize failure risk, save costs, and allow for quick course corrections if initiatives don't work.

• Isolate Faults: Design systems to contain failures within isolated zones, similar to circuit breakers in electrical systems, to prevent a failure in one area from affecting others.

• Automation over People: Prefer automation over human involvement for repetitive tasks. Automation is more consistent and often less expensive, making it more reliable and easier to tune for tasks like deployment, builds, testing, monitoring, and alerting.

25 more principle inspirations are available to paid subscribers below.

Read more

How we write code today is not innovative. People just keep forgetting and rediscovering patterns that have existed for 50 to 75 years, or even more considering much of software is mathematics.

Patterns are a shorthand that gets everyone on the same page quickly. If I say “event actor model” or “repository pattern,” even if you don’t know them, you can look them up and know what I mean without me having to explain it in detail.

Understanding that, instead of starting off designing or writing something from scratch, look for a pattern that matches your use case. You will be able to learn from the mistakes and successes of others. Maybe it’s the right pattern. Maybe it’s the wrong pattern.

At the very least, you will know what not to do. How else will you know that a Singleton is generally a bad idea if you don’t know what one is? You’ll just make one and not know its name.

By writing code, ignorant of patterns, you’re more likely to repeat the mistakes of others who learned the pros and cons of a particular pattern.

That’s good for learning, but bad for productivity.

Phases Of Pattern Usage

I see developers go through phases with patterns:

1. No idea about patterns
2. Starts seeing patterns
3. Realizes others recognized these patterns too
4. Sees many more patterns and starts applying them wrongly or too much
5. Realizes they went overboard
6. Shuns patterns as overkill
7. Thinks “hm, this looks like that pattern I used before”
8. Realizes patterns are good if applied to the problem they were meant to solve when needed
9. Realizes patterns, used pragmatically, are simpler than not using patterns

Typically, for people to learn phase 9, they have to go through all the phases. The sooner you understand this, the sooner you can use patterns to make things simpler, more quickly, and with a shared understanding.

But then, who should design? Effectively, all engineers.

• Junior Engineers design for small problems that only impact things the team owns

• Senior Engineers design for large problems that only impact things the team owns

• Staff Engineers design for problems that may impact things owned by other teams

• Principal Engineers design for problems that may impact many things owned by many other teams

• Architects design for problems that impact a majority of the teams and projects

For most designs, the person designing should be someone other than the Architect. Unless all your problems impact a majority of the teams and projects. In that case, I weep for you.

The Engineer that owns the design is the "Driver" of the design. Architects are always there to assist.

Let’s dig into the details.

Start with the Driver

In DACI terms, the Driver is the person who moves the project forward and is responsible for the decision-making process.

Ideally, Driver election is voluntary. To get everyone familiar with the concept, though, the Driver might need to be chosen. The Architects, Principal Engineers, or Engineering Managers should help with choosing.

What does "driving" mean for design?

A software design is a means to discuss a problem and how to address it. Ultimately, it results in a decision: How and whether we address the problem.

A design is only an artifact, though. Designing is an active process that involves many people. Without clear responsibilities, everyone assumes someone else will do it. To set clear responsibilities, there is exactly one Driver.

The Driver will endeavor to help everyone involved understand and agree on:

• the problem

• what the user needs

• the constraints we're working with

• what the business needs

• the risks involved

• potential solutions

• who is impacted

• what the impact is

• how we'll solve the problem

Essentially, the Driver aligns everyone on the user's experience, how the current solution fails to meet the user's needs, and how we think we can improve the user's experience. This, in effect, is design. So in effect, the Driver drives the design.

Drivers aren't just waiting for alignment and approval. They're "driving" for it. That means reaching out and figuring out "what do we need to do to move this forward?".

In practice, getting alignment means having conversations, researching, informing, and negotiating. The Driver doesn't do all this alone. Software development is a team activity. For a design, there may be many collaborators. An Architect or a more senior engineer that is familiar with the process is one of those collaborators.

Architects can help with:

• removing blockers

• identifying and connecting to stakeholders

• conveying technical strategy

• refining requirements

• managing expectations

• mitigating risks

With an Architect's high-level understanding and connections, it seems like they are the ideal person to drive the design.

Typically the higher level an engineer is, the more they should focus on strategy and elevating other engineers. Architects are no different. If Architects are doing all the designing, they will not have time to do any of their other responsibilities. Just as if a Staff+ Engineer is coding all day, they can not do any of their other responsibilities.

The team who is responsible for implementing the design and its Engineers are better suited to do the design.

Not only will they learn more, they will:

• feel more ownership of the solution

• better understand the needs of customers

• better understand the impact of their work

• build connections with other teams

In short, they'll be empowered with autonomy. Autonomy, is key to scaling software design.

Share Dev Details

The majority of software development happens between that range. 

Most developers work on application development, which is closer to system design than it is to low-level algorithms.

Most software development interviews are for jobs somewhere between application development and system design. Yet many interviewers do technical interview rounds only for algorithmic challenges and system design — nothing in between. 

The assumption here is that if you can solve algorithms and do system design, you have the skills to develop applications. That assumption is flawed. A broad range of skills is needed to develop applications. You will not get them by just practicing a hundred hours to recognize specific algorithm problem patterns. You also won’t get them by staring at overly simplified systems designs of Netflix, Uber, or Twitter X Threads.

You get application development skills by, well, developing applications. But many technical interviews do not assess those skills.

Algorithm Interviews

For clarity, I’m talking about LeetCode-style algorithmic problems. The majority of algorithmic interviews I’ve done were LeetCode medium and above. They’re often referred to as Data Structures and Algorithms (DSA).

Typically, during an algorithm interview, a candidate is given a problem and is expected to solve and evaluate the solution’s complexity using Big-O notation in less than 30 minutes. Often, the interview is longer, but time is taken up for introductions and other questions.

You’re expected to start by thinking through the problem aloud before writing any code. While solving the problem, you’re expected to explain your reasoning as you go along.

Here are some example problems:

• Maximal Square (LeetCode-Medium): Given an m x n binary matrix filled with 0's and 1's, find the largest square containing only 1's and return its area.

• Longest Substring Without Repeating Characters (LeetCode-Medium): Given a string s, find the length of the longest substring without repeating characters.

• Merge k Sorted Lists (LeetCode-Hard): You are given an array of k linked-lists lists, each linked-list is sorted in ascending order. Merge all the linked-lists into one sorted linked-list and return it.

These problems can be fun to solve when you have time to reason about them. However, in interview scenarios, the time constraint and general pressure of needing to pass to get a job can induce anxiety. To minimize anxiety, candidates prepare by practicing problems to become familiar with the patterns.

The standard advice from books like “Cracking The Coding Interview” (recommended reading by Meta) is to spend several weeks to several months on preparation, depending on your current skill level and familiarity with Data Structures and Algorithms.

LeetCode's “Interview Crash Course” includes 93+ walkthroughs of example problems, 67+ curated practice problems, and 12 quizzes. To get through all this content while you’re also presumably working or otherwise living your life can take months.

This brings me to my next point.

Don't waste a candidate's valuable time

A typical set of interviews includes two algorithm rounds and a system design round. 66% of the technical interview is dedicated to something you will likely code less than 1% of during your entire career.

I've been doing software development for more than two decades. The only time I study algorithms is:

• For fun. Difficult challenges can be fun in your free time when no pressure exists.

• For an interview.

If they appear in the course of my actual work, I use a (typically built-in) library that is battle tested. Without specializing in that type of work, there is no way I could improve upon them.

Very few people learn algorithmic development on the job. It requires hours of personal time to practice enough of them to be useful in an interview. They are not job relevant for most developers.

Algorithm interviews get false signals

Algorithmic challenges in an interview signal only one thing: 

• You practiced algorithmic challenges enough to recognize their patterns and solve them.

But, they do not signal general development skills. They signal pattern recognition of specific algorithms and preparation more than they signal problem-solving.

By focusing on a person's ability to solve algorithms under the extreme pressure of the artificial interview environment, you ignore other factors necessary for application development. The biggest being that a candidate can turn business requirements into a solution that solves that business need. Few customers have ever needed you to bubble sort better than another vendor. Besides, AI can already do that better than humans (AlphaDev uncovers up-to 70% faster algorithm for libcc++ sorting library).

In the best case, you find candidates that can productively develop applications. In the nominal case, you find candidates that have studied algorithms well enough to pass the interview. In the worst case, you alienate many candidates that do not perform well with "gotcha" type algorithm questions, such as candidates with neurodivergence.

Alternatives considered

So what should you do instead of using algorithms in interviews?

Create tests more like what you expect the developer to do regularly and which skills are essential for that work. 

For example, focus on getting signals for:

• Interpreting business needs, functional requirements, and non-functional requirements into efficient solutions.

• Breaking down complex projects into manageable tasks and steps.

• Application of design patterns.

• Use Architecture Principles like Event Driven Design, API First, and Buy vs. Build.

• Evaluating what is worth automating (ex: builds and tests in a CI pipeline).

• Reviewing code effectively and understanding the benefits of this process.

• Comparing tradeoffs between threading and async coroutines for server construction.

• Identifying opportunities for performance optimization in code.

• Debugging and resolving issues in a given piece of code.

• Refactoring code for improved readability and maintainability.

• Integrating APIs effectively in software applications.

Unsure of where to start with such a test? Coding Challenges is an excellent resource for challenges that fit these requirements. They're great for interviews or preparing for interviews.

Should I learn algorithms?

Studying algorithms will make you a better overall developer. But that doesn’t mean you need to be good at solving them in under 30 minutes while explaining your thinking. Being able to do that has nothing to do with real word software problems. It’s only useful for the artificial interview environments that are broken and should be changed.

I recommend you learn challenging algorithms when you have free time and are under no pressure to get a new job. The best thing you actually learn from studying them that can be applied to broader areas is Big-O notation and complexity. Understanding Big-O will help you see unneeded complexity in application and system development.

If you’re applying to jobs that have algorithm interviews, then you have two options:

1. Refuse to do algorithm interviews.

2. Learn algorithms and practice them in an interview like environment.

Only one of those will give you a chance to get that particular job. If you want that job, do #2.

These interviews are flawed. Unfortunately, if you’re trying to get a job and don’t have the luxury of refusing to do these types of interviews, then you must do them to get the job.

Here’s a list of resources to learn algorithms and Big-O to help you.

Conclusion

I want to see change in the way we do technical interviews. I don’t do these types of problems when I give interviews. My goal is to bring awareness so others will change the way they interview.

If you are giving an interview, consider how you evaluate technical ability. If the job you are interviewing for actually involves working on deep algorithms, absolutely go ahead and test that. If your job is application development or more abstract: cut it out.

Updated

2023/09/09 clarified my stance in “Conclusion” and “Should I learn algorithms?”. Clarified what I mean by “extreme pressure”.

2023/09/08 added “Algorithm Interviews” section and some clarifications (like “async coroutines”) based on feedback from The Primeagen's reaction video.

Then the unexpected happened:

• Before the dotcom crash, the firm had a website to sell house plans.

• The original developers abandoned the project. 

• I was good with computers and had done simple HTML websites, so the owner asked me to take a look.

I was enamored. This was the first time I saw a website that actually did something useful for a business. No longer was coding just a fun exercise — it provided real value.

I learned how to program a new language and started managing the website alongside my drafting duties. Over time, the website gained more traction. More and more, I was coding instead of drafting.

Eventually, I decided to go to school for computer science instead of architecture.

What changed my mind was not just software development's interesting engineering challenges.

It was that I could provide much more real value to a business with just text on a screen. It was amazing!

While my path changed, it wasn't as big a leap as it may seem.

Software and building architecture both require a deep understanding and passion for the principles of design, architecture, mentoring, and project planning.

The end result? My hobbies flipped:

• When I was a teenager, software was a hobby, and my career path was building design. 

• As an adult, my career is in software, and my hobby is interior design and building.
  

When I'm not doing software architecture at work ⌨️, I'm remodeling my home 🔨. It allows me to connect better with the physical world.

The site actually still exists.

It continued to operate as an outlet for thousands of house plans for hundred of designers for more than 20 years. Even after leaving the company, I did contract work for it from time to time.

It still exists today, but it only represents the original architecture firm as times have changed with social media.

So that makes it the longest continually running web service that I have worked on.

• In Part 1, we discussed setup and best practices and answered the question: “Will AI replace software developers?”.

• In Part 2, we designed a solution and created a design document.

• In Part 3, we generated a sequence diagram and an OpenAPI specification.

• In Part 4, we generated tests. First.

• In Part 5, we’ll generate the application code.

Recap: URL Shortening Service, generated by AI

• We’re writing a solution for the URL Shortener Challenge.

• We’ve got a great design that we visualized with PlantUML and generated OpenAPI specifications for.

• ChatGPT generated some tests.

• Developers that use AI will replace those who don't  — It will take more time before AI completely replaces developers.

Generating an application from tests

If you’re not a fan of Test First development like me, you’re glad to finally be writing application code. You’re probably wondering why we didn’t just start there and ignore all this design and business needs nonsense. You might want to learn about how all this nonsense makes teams autonomous.

Boilerplate

Boilerplate first. The code base has to be set up. I asked ChatGPT to give me commands for the poetry stuff. I’ll summarize it here.

• Using poetry to manage dependencies, create a pyproject.toml file with poetry init, adding connexion and redis as a dependency.

• poetry add --dev the test dependencies like pytest, freezegun, and fakeredis.

• Paste tests into test_shorty.py

• Run the tests.

Of course, they fail; we have no application code.

Generate the code for real this time

To generate the code, I’m using CodeGPT plugin for PyCharm.

I select the code and use this prompt:

Write an implementation that satisfies these tests in the selected code. Here is the design doc:

{complete design document}

Note the “selected text” part. It uses whatever I have selected in the IDE as part of the input.

import hashlib
import random
import string
from datetime import timedelta
from flask import Flask, jsonify, redirect, request, url_for
from redis import Redis

app = Flask(__name__)
redis = Redis(host='redis', port=6379)

BASE_URL = "http://example.com/"
...

🛑 Stop generating!

It did a decent implementation, but it forgot one important piece:

Not quite. This uses connexion as specified in the specs.

After a quick and familiar apology:

My apologies for that mistake.

Here is the updated source code using connexion:

import hashlib
import random
import string
from datetime import timedelta
import connexion
from redis import Redis


app = connexion.FlaskApp(__name__, specification_dir="./")
app.add_api("openapi.yaml")


redis = Redis(host='redis', port=6379)

BASE_URL = "http://example.com/"

def generate_short_code(url: str) -> str:
    """
    Generate a short code for the given URL.
    """
    # Generate a unique hash for the URL using SHA1
    sha1_hash = hashlib.sha1(url.encode('utf-8')).hexdigest()
    # Convert the hash to base62
    base62_hash = encode_base_n(int(sha1_hash, 16), 62)
    # Truncate the hash to 7 characters to get the short code
    short_code = base62_hash[:7]
    return short_code

...etc etc

And just like that, it’s done. The code was close to correct without much cajoling because it had the tests and the design doc to work with.

It did need some corrections, though. The following prompts were followed by selecting the relevant part of the code and explaining the problem:

• The url_sha1 should be base62 encoded instead of hex encoded.

• base62 is not a real module. Use the existing encode_base_n function instead

• In the selected code, there is a lot of duplication. Be DRY.

  • That made the duplication worse. 🤦🏼

• Why is the selected code getting a TypeError('not all arguments converted during bytes formatting')

• How do I convert bytes to an int? (Yes, I was being lazy)

After many apologies, we got a good enough solution for me to take over with.

Make it work

The next part is not glamorous unless you like Test First development 🤩.

• Run the tests.

• Get an error.

• Fix the error by letting CodeWhisperer auto-complete your thoughts.

• Repeat until all the tests pass.

You can view the complete code along with:

• Design Document

• PlantUML diagram

• OpenAPI specification

• Tests

• Prompts

• A note from our AI partner

Conclusion

• Most of the time was spent designing a solution with ChatGPT.

• But that made everything else go faster.

• The design doc was fed into the prompt to generate tests, generating correct tests nearly immediately.

• Asking AI to generate code that satisfies a selected set of tests is freaky, but it works. It would not work as well if I didn’t supply it a design doc first.

• The moral of this really is:

  • Design First

  • API First

  • Test First

• Whether you get AI to help you with each stage or not, your results will be better, less error-prone, and faster.

• And doing it with AI is faster and fun but also frustrating.

Alternatives Considered

What if I skipped all this design, test, PlantUML, etc. stuff and just pasted the challenge as a prompt into ChatGPT 4?

• For a well know problem like a URL Shortener, it will give you working code right away.

• When I tried it, it generated a partial “example” Javascript solution using the Express framework and MongoDB for storage.

• I could tell it, “Write it in Python backed by redis.”

• Then I could ask for alternatives to generating short URLs other than random letter choices.

• And then I could ask it to write tests.

• I could walk through each minor change with it and eventually come to a similar solution as starting with the design first.

• Maybe I would have thought about traffic loads and other non-functional requirements. Maybe I would have thought of expiring URLs.

Here’s the thing, though.

That might be okay when a quick and dirty solution is sufficient. My goal was to show you a practical example of how you can use generative AI to aid your work.

At a certain level, quick and dirty is not good enough.

By writing the design document first, we had thought through all the major details, so it was quick and easy when it came time to write code. Notice how this part of the article series was the shortest?

We could also have handed the design document to someone else, perhaps someone to develop the UI. Perhaps another AI. We would not have to walk them through every step to figure out what the software should do in order to generate the UI.

We’d start with the design doc and tell them to write code for it.

The design doc, the diagrams, and the API specification all contribute to making collaboration with other developers (human or AI) faster and more productive.

Next

All done. Thanks for the journey.

• Part 1: Setup and Process

• Part 2: Design

• Part 3: Sequence diagram and API specification

• Part 4 Generating tests

• Part 5: Generating the application and making it work ← YOU ARE HERE

• In Part 1, we discussed setup and best practices and answered the question: “Will AI replace software developers?”.

• In Part 2, we designed a solution and created a design document.

• In Part 3, we generated a sequence diagram and an OpenAPI specification.

• In Part 4, we’ll generate tests.

Recap: URL Shortening Service

• We’re writing a solution for the URL Shortener Challenge.

• We’ve got a great design.

• AI won't replace developers; developers that use AI will replace those who don't.  

Test First

I like Test Driven Development development. I usually write tests during coding -- interwoven with my coding.

In this case, I'm generating tests first, then using a different tool to write application code to demonstrate using AI in multiple ways.

Good tests describe the business use cases of our software. So, like the other prompts, let’s use our design document for this prompt.

You and I are software engineers. We will use pair-development. Our goal is to craft the best possible application to satisfy the design. 

We will follow this process:

1. You will write tests that fit the design
2. We'll discuss the tests until they satisfy the design

{complete design document}

It’s important to note a critical part of the design document. At the end is a style guide. This style guide drives how ChatGPT will generate the tests.

## Style Guide

Our organization follows these principles for development.

- DRY
- SOLID
- TDD

Our company follows these coding styles and best practices:

- Use Python `black` formatting.
- Use Python type hints.
- Pytest for testing.
- Testing:
    - All business use cases should be covered in the tests.
    - Focus testing on business case functional testing to test at API
      boundaries such as REST APIs -- not class-level
      tests.
    - For fake data use "example" in the name. "test" must only be used for the
      test names themselves.
    - If monkey-patching or other dependency injection is necessary, only do so
      in pytest fixtures -- no dependency
      injection in tests themselves.
    - Use testing analogs for external dependencies like databases. Do not use
      test analogs for our own code.
    - Testing analogs should function the same as the libraries and services
      they mimic. Only implement as much analog
      functionality as needed for the test.
    - For test analogs, use "fake" in the name.

ChatGPT takes this into account when generating the tests:

import pytest
from datetime import timedelta
from freezegun import freeze_time
from urllib.parse import urlparse
from your_app import create_app
from your_app.shortener import url_hash, generate_short_code

# create a fixture for test client
@pytest.fixture
def client():
    app = create_app()
    with app.test_client() as client:
        yield client

def test_shorten_valid_url(client):
    url = "https://www.very-long-url.com/"
    response = client.post('/shorten', json={'url': url})
    assert response.status_code == 200
    assert 'url' in response.get_json()
    short_code = urlparse(response.get_json()['url']).path.strip('/')
    assert short_code == generate_short_code(url_hash(url))

def test_redirect_to_long_url(client):
    url = "https://www.very-long-url.com/"
    # first we need to generate the short URL
    response = client.post('/shorten', json={'url': url})
    assert response.status_code == 200
    short_code = urlparse(response.get_json()['url']).path.strip('/')
    # then we use the short URL
    response = client.get('/' + short_code)
    assert response.status_code == 302
    assert response.headers['Location'] == url

@freeze_time("2023-06-10")
def test_expired_short_url(client):
    url = "https://www.very-long-url.com/"
    # first we generate the short URL
    response = client.post('/shorten', json={'url': url})
    assert response.status_code == 200
    short_code = urlparse(response.get_json()['url']).path.strip('/')
    # then we time travel 24 hours into the future
    with freeze_time("2023-06-11"):
        response = client.get('/' + short_code)
        assert response.status_code == 404

# [truncated]

This is close. It covered most of the use cases in the first pass and styled the code based on the style guide.

Like with most of the other design and development phases with ChatGPT, this will be a conversation to generate optimal results.

- generate_short_code is not idempotent so we can not use it this way in our tests. To verify the URL is shortened, validate the output URL matches the requirements, then call it to verify we are redirected.
- Call the app "shorty"
- Remember to use black formatting
- Do we have any external dependencies we need to fake?

You're right about the idempotence, my mistake. Instead, we'll validate the shortened URL by checking its length and calling it to verify the redirection.

As for external dependencies, we are using Redis as our backend storage. When testing, we don't want to rely on an actual Redis instance as it might not be available or it might have unexpected data. Therefore, we'll use a fake Redis server for our tests. Python has a library for that called fakeredis.

Now, let's modify our tests to use "shorty" as the app name and to use fakeredis. We'll also format the tests using black:

from shorty import create_app
from fakeredis import FakeStrictRedis

@pytest.fixture
def client():
    app = create_app()
    app.config["REDIS"] = FakeStrictRedis()

    with app.test_client() as client:
        yield client

More revisions, please.

- test_redirect_to_long_url is now redundant. 
- Are there any other use cases we should cover?

You're correct. The test_shorten_valid_url test already covers the redirection to the long URL, so test_redirect_to_long_url is indeed redundant.

As for other use cases, we could add a test for the case where the user tries to access a non-existent short URL. This could happen if a user makes a typo when entering the URL manually, or if there's an issue with the code generating or storing the short URLs.

Here's a test for this use case:

def test_nonexistent_short_url(client):
    response = client.get("/nonexistent")
    assert response.status_code == 404
    assert "error" in response.get_data(as_text=True)

Additionally, we should consider adding a test to ensure that the shortened URLs are unique for different long URLs within the 24-hour period. Here is a test case for that:

We continue:

looks good. One revision, for test_nonexistent_short_url, validate the error string contains a human friendly message. Generate the new test file.

Then ChatGPT forgets what it’s doing:

Some test cases are now missing such as expired URL. What happened to fakeredis?

My apologies for the confusion. Let's reintroduce the missing test case for an expired URL and include the fakeredis as a fixture for testing Redis-related functionality. Below are the changes:

At least we can get it back on track easily.

After a few iterations, we have a complete set of tests.

ChatGPT has understood our testing requirements. If I did not specify them, it would have generated less useful unit tests, used poor naming conventions, and littered test code with dependency injection.

The final results needed a few small tweaks to get the boilerplate setup done correctly. The tests themselves were spot on.

You can view the completed test file.

Now we can take these tests, drop them into our IDE and write code to satisfy them.

Next

Head to Part 5. Continue the journey.

• Part 1: Setup and Process

• Part 2: Design

• Part 3: Sequence diagram and API specification

• Part 4: Generating tests ← YOU ARE HERE

• Part 5: Generating the application and making it work

• In Part 1, we discussed setup and best practices and answered the question: “Will AI replace software developers?”.

• In Part 2, we designed a solution and created a design document.

• In Part 3, we will generate a sequence diagram and an OpenAPI specification.

Recap: URL Shortening Service

• We’re writing a solution for the URL Shortener Challenge.

• We’ve got a great design.

Visualizing The Design

Few things explain what software is supposed to do more than a sequence diagram.

• ChatGPT can’t currently generate images, but it can generate PlantUML text diagrams, and we can feed that into the online renderer (or, as I prefer, an IDE plugin) to get an image.

To visualize the design, I asked ChatGPT 4 (3.5 was not working out) to generate the diagram.

Write a PlantUML sequence diagram for the API interactions of the design below.

- Use descriptive aliases. Don't use one-letter aliases.
- Activate/deactivate each component in the sequence diagram when appropriate
- Separate use cases with section titles
- Use "actor" instead of `participant` for the user
- Include each record of the data model that we need to store

{complete design document}

That’s pretty good. You can also view the PlantUML source or an SVG.

API First

I like API First development.

• It helps to get everyone on the same page of what the API will be before any code is written.

• I use OpenAPI to describe APIs and share the specifications with team members.

• UI developers can start coding without the server, and server developers can start coding without a UI.

• When they’re both done, they integrate, and since the API was agreed upon first, it just works.

So let’s have ChatGPT generate the OpenAPI spec.

Your task is to generate an OpenAPI specification for API described in the 
design doc below.

- Included example requests and responses to cover the defined use cases.
- Provide example HTML errors in the spec.
- Use the PEP-8 standard for naming Python functions
- For the example domain, use `example.com`
- The error message should be in an `error` key
- Since we're using connexion, the operationId should point to the Python module 
  and function that will handle the request

{complete design document}

• Here ChatGPT 3.5 worked well.

• ChatGPT 4 provided more thorough results with better examples.

openapi: 3.0.0
info:
  title: URL Shortening Service
  description: Service to shorten long URLs.
  version: 1.0.0
servers:
  - url: https://example.com/
paths:
  /shorten:
    post:
      summary: Shorten a URL
      operationId: shorty.shorten_url
      requestBody:
        description: URL to shorten
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Url'
            examples:
              shortenUrlRequest:
                value:
                  url: "https://www.very-long-url.com/"

You can view the complete generated OpenAPI specification.

We’ll use this OpenAPI specification in our application development.

Next

Head to Part 4. Continue the journey.

• Part 1: Setup and Process

• Part 2: Design

• Part 3: Sequence diagram and API specification ← YOU ARE HERE

• Part 4: Generating tests

• Part 5: Generating the application and making it work

• In Part 1, we discussed setup and best practices and answered the question: “Will AI replace software developers?”.

• In Part 2, we will design a solution and create a design document.

Recap: The Scenario

AI is pretty great at leet code examples. I am not. Also, I said this would be a practical example. Leet code is not indicative of real-life work. 

For practical examples, it helps to use something similar to real-life work. 

• Coding Challenges is an excellent resource for building real-world applications. 

• A URL Shortener Challenge looks like a good, practical example to work with.

Design

I’ve formulated a prompt that lays out the roles, goals, and process and establishes the AI as a collaborator. I’ve also included the Design Document template in the prompt to help guide the end result.

I used ChatGPT 3.5 for this portion. I also used ChatGPT 4 as a test run, and it yielded better results, but I want to give you an idea of what 3.5 is capable of.

I started off by prompting ChatGPT:

You and I are software engineers. We will design software together. Our goal is to design the best possible application to satisfy the business requirements. 

Ask me clarifying questions as needed.

We will follow this process:

1. Discuss problem context
2. Discuss use cases
3. Discuss functional requirements
4. Discuss non-functional requirements (traffic, SLA, security, privacy, etc.)
5. Discuss data model
6. Discuss implementation details
7. Discuss observability (monitoring, logging)
8. Discuss any remaining design sections.
9. Finalize design.

At the end of each step in the process, we will update the design document.

Here is the design document template:

# {Design Name}

## Context

{Describe the problem}  

## Functional Requirements

- {requirement 1}

## Non-functional requirements

- {requirement 1}

## Use Cases

{Business use cases and user experience}

- {use case 1}

## Exclusions

{Things we are explicitly not doing}

- {exclusion 1}

## Implementation Details

- {detail 1}

### {Topic}
  
- {detail 1}

### Data Model

{data model overview}

#### {model 1}

{model description}

### Input Validation

- {validation}

## Observability

### Metrics

- {metric 1}

### Logging

- {logging 1}

## Privacy and Security

- {security 1}

## Deployment

- {deployment 1}

## API

The API has the following endpoints:

1. `{path}` - A `{HTTP method}` endpoint {description}.

## Style Guide

Our organization follows these principles for development.

- DRY
- SOLID
- TDD

Our company follows these coding styles and best practices:

- {style 1}

Great! Let's begin the process of designing the software application.

Step 1: Discuss problem context

Could you please provide some details about the problem that the application needs to solve? It would be helpful to understand the business domain, target users, and any specific pain points or goals that the application aims to address.

Okay, it picked up on the process and is guiding us.

I gave it the first bit of our URL shortener coding challenge:

This challenge is to build your own URL shortening service. Think bit.ly or tinyurl.com.

Basically it’s a service that lets a client submit a long URL which is then shortened to make it easier to use. For example:

https://www.amazon.com/Rust-Programming-Language-2nd/dp/1718503105/ref=sr_1_1?crid=3977W67XGQPJR&keywords=the+rust+programming+language&qid=1685542718&sprefix=the+%2Caps%2C3079&sr=8-1

could become: https://tinyurl.com/bdds8utd

This is typically done with a web based user interface, that let’s users enter a long URL and get back a shortened version of the URL. For example:


The shortening service then keeps a record of the short code, i.e. bdds8utd in the example above and the long URL that it maps to. Then when a client requests the shortened URL the service returns a HTTP redirect code, sending them to the long URL.

Thank you for providing the problem context. I understand that we need to build a URL shortening service that takes a long URL as input and provides a shortened version of the URL as output. The service should also store a mapping between the shortened URL and the corresponding long URL. When a client accesses the shortened URL, they should be redirected to the original long URL.

Let's move on to the next step.

Step 2: Discuss use cases

Can you provide some specific use cases or scenarios that users might encounter when using the URL shortening service?

I could think up use cases here, but let’s see what ChatGPT thinks:

What use cases do you foresee?

1. Shorten URL: Users can input a long URL into the service and request a shortened URL.

2. Retrieve Short URL: Users can retrieve the shortened URL associated with a specific long URL.

3. Redirect to Long URL: When users access a shortened URL, they are redirected to the original long URL.

4. Analytics and Statistics: The service can provide analytics and statistics on the usage of the shortened URLs, such as the number of clicks or the geographical location of the users.

Analytics is a realistic business need, but it’s too much work for our example.

We will not worry about analytics in this version. Let's continue with those use cases.

Understood.

Let's proceed to the next step.

Step 3: Discuss functional requirements

From the use cases we discussed, here are the functional requirements:

1. Shorten URL

   • The service should accept a long URL from the user.

   • It should generate a unique shortened URL for the given long URL.

   • The mapping between the shortened URL and the long URL should be stored in the system.

   • The shortened URL should be returned to the user.

2. Retrieve Short URL

   • The service should allow users to retrieve the original long URL associated with a specific shortened URL.

3. Redirect to Long URL

   • When a user accesses a shortened URL, the service should redirect them to the corresponding long URL.

Cool. This time ChatGPT anticipated functional requirements.

Let’s throw in some more:

- The code should be short, less than 10 chars
- The API should be a JSON API
- When visiting a short URL that is not found, the response should be an HTML error page with an appropriate HTTP status code and an error message instead of JSON

Great! I've added the additional functional requirements you mentioned

Step 4: Discuss non-functional requirements

In addition to the functional requirements, we should also consider the non-functional requirements that are important for the successful operation and performance of the URL shortening service.

💡 Don’t worry. I’m not going to paste all the output. I wanted to give you a sense that it does (more or less) know what it’s talking about. I’ll summarize the conversation more from here on out.

ChatGPT wants to jump to listing non-functional requirements. I would like to brainstorm here. Our traffic needs will dictate some non-functional requirements, so we’ll start there.

Let's estimate how much traffic we will have and how many URLs we need to store. How much traffic should we expect?

• Daily Traffic: Assume a moderate number of users initially, such as 1000 requests per day.

• Request Rate: Assuming a uniform distribution of requests throughout the day, we can estimate around 70 requests per hour (1000 requests / 24 hours).

• Peak Traffic: Consider the possibility of occasional spikes in traffic, especially during peak usage times. We can assume a peak traffic rate of 2-3 times the average request rate, resulting in around 140-210 requests per hour during peak periods.

🥱 This is a very modest traffic load. It’s probably realistic for a service with no marketing budget, but it would be hard to code something that doesn’t meet these needs. Let’s spice it up a little bit.

I asked my coding partner some leading questions to figure out what we could handle on a modest budget instead.

Let's work backwards from storage to see what capacity we could support. We will store the data in-memory in Redis. We only want to use 2GB of RAM. How many URLs can we store?

• Assume each URL entry requires 100 bytes of memory. This includes the long URL, the shortened URL, and any additional metadata.

• Considering the 2GB RAM constraint, we have approximately 2,000,000,000 bytes available.

Hm 🤔. I’m no mathematician magician, but that looks off. ChatGPT 3.5 seems to have issues doing math calculations. I will skip over the glaring calculation detail for now and address the more significant issue first.

100 bytes seems short for a URL shortener. Likely users will want to shorten much longer URLs. What should we plan for for long URLs?

So, with an estimated average URL entry size of 500 bytes, we can store approximately 4 million URLs in Redis while utilizing 2GB of RAM.

Okay. The math checks out this time. But 500 seems arbitrary. I’ll guide ChatGPT to a more informed choice with some leading questions.

What is the maximum URL length?

The maximum length of a URL is not strictly defined by any standard or specification.

For practical purposes, it's recommended to consider keeping URLs reasonably concise and within a reasonable length limit, typically around 2,000 to 4,000 characters.

Do web browsers impose a limit?

Yes, web browsers do impose a limit on the length of URLs they can handle. This limit is set by the individual browsers and can vary across different browser versions.

The maximum URL length that browsers can handle typically ranges from 2,000 to 8,000 characters.

👀 My independent research of Googling things and clicking on random StackOverflow links says various degrees of “some browsers support a ridiculously long URL, but you’ll have the most compatibility with around 2,000 characters.”

So I make a judgment call of using 1000 bytes on average for our calculations.

ChatGPT 3.5 can often be wrong on calculations. It helps to ask for more detail in tables to see if it’s thinking correctly.

Let's plan for an average of 1000 bytes per URL. Give me a table of traffic and data estimates for this size of URL as well as the total RAM we'll need. We will want to allow room for spikes in traffic. Allow for a 10x spike.

Include the columns: scale, urls per hour, urls per day, urls per month, data per day, data per month

Show rows for different RAM amounts: 1 GB, 2 GB, 4 GB.

Sure! Let's estimate the traffic and data requirements based on an average URL size of 1000 bytes, and also factor in spikes in traffic.

I didn’t bother checking if those numbers were correct. It’s not really the data I’m looking for. I want ChatGPT to figure out how many URLs the RAM can hold at a maximum.

Those numbers aren't reaching anywhere near the RAM limits. Let's figure out the maximum data we can handle for each RAM amount.

Apologies for the confusion. Let's calculate the maximum data we can handle for each RAM amount, considering the URL size of 1000 bytes.

Okay. Back to bad math.

That does not add up. `1,073,741,824 bytes / 1000 bytes` is not 1,073,741,824

Apologies for the error in the calculation. You're correct; the division was incorrect in the previous response.

I apologize for the confusion caused by the previous incorrect calculations.

The data is still not quite right. What I do notice is that ChatGPT 3.5 apologizes… a lot. It gets pretty annoying. It seems ChatGPT 4 apologizes less often. Maybe because it’s correct more often and does not need to.

I decide to take the coaching approach and slightly change to a leading direction:

How do we calculate how many URLs will fit in a given amount of RAM?

For example, if the average URL size is 1000 bytes and you have 1 GB (1,073,741,824 bytes) of available RAM, the calculation would be:

Maximum URLs = 1,073,741,824 bytes / 1000 bytes = 1,073,741 URLs

Okay, so it knows what to do. Let’s see if it is set on the right path.

okay. Given that formula, update the table.

Apologies for the confusion earlier.

🤦🏼 *facepalm*

I apologize for the confusion and any frustration caused. I understand the importance of accurate information in the design process.

At least it knows I’m frustrated.

For those of you bad at math like me, 2.15 trillion bytes is 2,105 GB — not 2 GB. I guess there’s that, I’m better at math than ChatGPT 3.5.

I simplify the problem for it.

We have 3 scales: Small (1GB RAM), Medium (2GB RAM), Large (4GB RAM)

Create a table with these columns: scale, urls, total data

Work backward from the total data, which must be no higher than the RAM amount. We want to figure out for a given RAM amount, how many URLs can we fit.

Looks like it figured it out. We walked through some more calculations then I came to this conclusion:

If we want to keep data only in memory, we'll either need a lot more RAM or to only store data for a short amount of time.

So I figure:

Let's be the SnapChat of URLs shorteners and only store the URLs for 24 hours. That should be long enough for quick sharing of URLs and allow us to use an in memory store like Redis. Right?

Storing URLs for a short period of time aligns with the goal of a temporary and ephemeral URL shortening service, similar to the concept of SnapChat.

Not an enthusiastic endorsement, but I’ll take it.

Okay, let's plan for a max of ~200,000 URLs of capacity. Even though we 
only store URLs for 24 hours, we want to make sure we do not repeat URLs for 10 years. How many possible URLs is that and what's the shortest short code we can use to represent that number?

Let’s skip ahead.

We won't be storing the short codes, so we won't really know about duplicates for 10 years. Instead, we need to make it statistically unlikely that we'll hit a duplicate in that time frame. We do want to verify there are no duplicates for the 24-hour window we're storing data. We could use a random ID for the short code, base62 encoded. How many random bits do we need to avoid collisions for 10 years?

⚠️ Spoiler alert. This does not go well. ⚠️

After much back in forth, I came to this conclusion:

Your math is off so I asked ChatGPT 4. Here's what we came up with:

A 10 character short code would make collision very unlikely. I'd prefer smaller, so let's go with 8 chars. It's unlikely enough for normal traffic. We don't expect a 10x spike every day for 10 years.

Thank you for providing the updated information and the calculations. I apologize for any confusion caused by the previous responses.

Yes, I cheated and asked ChatGPT 3.5’s more intelligent cousin, ChatGPT 4. But it did not take it hard; it ignored this and accepted the answer with an apology.

Now that the calculations are out of the way, we can do work that ChatGPT 3.5 is better suited for.

This discussion implied some new functional and non-functional requirements. What are they?

Functional Requirements:

1. Generate Unique Short Codes: The system should generate unique short codes for each long URL to avoid collisions and ensure uniqueness within the desired time frame.

2. Store URLs for a Limited Duration: URLs should be stored in memory for a maximum duration of 24 hours, aligning with the temporary nature of the service.

3. Remove Expired URLs: The system should automatically remove expired URLs from storage after the designated 24-hour period.

4. Handle 10x Traffic Spike: The system should be able to handle a spike in traffic up to 10 times the normal volume to accommodate occasional high-demand periods.

5. Redirect to Long URLs: When a short URL is accessed, the system should redirect users to the corresponding long URL.

Non-Functional Requirements:

1. Collision Probability: The system should have a low collision probability for generated short codes, ensuring that the likelihood of duplicate codes is statistically unlikely.

2. Compact Short Codes: The short codes should be reasonably short in length, striking a balance between compactness and collision avoidance.

We carry on like this back and forth on several topics:

• What is the next step in our process?

• Okay, let's move on to the data model. What do we need to store?

• For the use case "User submits the same long URL multiple times and receives the same short URL within the 24-hour duration.", we will need to store additional data.

• This will add some additional storage for each URL. Considering the two mappings in our data model, how much will each URL take in space?

• What do you think the API should be?

• etc

I have to remind it:

Don't be so apologetic. We're working on this together.

Thank you for your understanding and kind words! I appreciate your collaborative approach, and I'm here to assist you throughout the process. If you have any more questions, need further clarification, or require assistance with any aspect of the design, please don't hesitate to let me know. Let's continue working together to create a successful URL shortening service design.

You can see this is a conversation. ChatGPT and I are designing together. ChatGPT is informing me, and I’m making the decisions. Using the DACI model, I would be the Driver and the Approver, and ChatGPT would be a Contributor.

We went back and forth, converging on a design. If you’re interested, view the whole interaction.

And here’s a snippet of the design we came up with. We’ll use it in Part 3 and beyond.

# URL Shortening Service

## Context

This service provides APIs that take long URLs and provide a short URL suitable for easy sharing.

## Functional Requirements

- The JSON API should allow users to submit a long URL and receive a shortened URL in return.
- When visiting the shortened URL, the visitor will be redirected to the long URL.
- When visiting a short URL that is not found or has expired, the response should be an HTML error page with an appropriate HTTP status code and an error message. The error page should provide a user-friendly display.
- Short URLs are only valid for 24 hours. After the 24-hour validity window, a new short URL should be generated for the same long URL.

[truncated]

## Non-functional requirements

- Be able to handle generating and storing ~200,000 short URLs a day and up to 2,000,000 short URLs in a day during a 10x spike in URL generation.
- Use minimal memory, up to 2GB.

[truncated]

## Use Cases

- User submits a long URL and receives a short URL in response.
- User visits the short URL and gets redirected to the original long URL.
- User attempts to access an expired short URL and receives an appropriate response.
- User submits an invalid long URL and gets an error response.

[truncated]

You can view the complete design document.

We can now use this design document to generate some code.

Next

Head to Part 3. Continue the journey.

• Part 1: Setup and Process

• Part 2: Design ← YOU ARE HERE

• Part 3: Sequence diagram and API specification

• Part 4: Generating tests

• Part 5: Generating the application and making it work

I've developed some techniques for working with AI coding tools that get good results. Here, I'll focus on how you can add generative AI to your workflow.

I've done this exercise as a live demo before. Showing someone how to do something opens doors to many previously unthought possibilities.

Let me give you the details.

But first, let's discuss the question I'm asked most often when I demo: 

Will AI replace software developers?

Everyone has been talking about generative AI for development, but I have yet to see practical examples of its use. Many posts say how AI will replace all of us developers. Many posts show examples of generated code doing simple things -- often incorrectly. A few have come to the same conclusion as I have: 

AI won't replace developers; developers that use AI will replace those who don't.  

At least in the short term. 

• Eventually, AI may replace software developers. 

• In the meantime, I'm embracing it and figuring out how it can make me more efficient.

It's dangerous to go alone!

• Treat the AI like a coding companion -- you are pair programming. It has access to a lot of knowledge and can put it to use quickly. You are a reasoning being and have insight that the AI doesn't. Do what you do best and let it do what it does best. 

• Be specific; be precise. AI is not omniscient. It can't read your mind (*yet). A fun way to ask AI to teach you something complex: "Explain X like I'm 10" or "Explain X in layman's terms." Do the reverse. Explain what you want in exacting detail; otherwise, the AI will make assumptions or make stuff up. Pro tip: Tell it to ask clarifying questions. 

• You must already know what you're doing, or you won't know if the AI is right. Only do this for languages and libraries you are intimately familiar with. At the very least, you should know the language well and be willing to learn the library instead of just copy-pasting whatever the AI generates. You are the editor. You need to understand what it is generating.

• Be fully engaged. The goal is to speed up your development -- not have the AI do all the work.

You might see a common theme with these tips. The experience is very much like pair programming. Consider it like you're the lead on a project pairing with a junior developer. A junior developer that just so happens to know most of the internet before September 2021. 

Take this

No one AI tool does everything. I've tried several; for this example, we'll keep it simple.

• ChatGPT will do the bulk of the generating. You could do this with GPT 3.5 or 4. I find 4 much better at generating code and understanding context. But GPT 4 is limited to 25 messages every 3 hours and requires ChatGPT Plus. I'll give more tips on how to make the most of those 25 messages later.

• CodeWhisperer will handle auto-complete. I'm currently using this over Copilot because I like its PyCharm plugin better.

• CodeGPT plugin will let our IDE talk to ChatGPT (but not that CodeGPT). I use the IntelliJ plugin. I have yet to try the unrelated CodeGPT service, which only provides a VSCode plugin. The goal here is to have ChatGPT integrated into the IDE. Some of these don't have GPT 4 access, so we still need to use the standalone ChatGPT if we want to use that.

ChatGPT is not the only tool. Whatever you're trying to do, there's an AI for that. For this example, though, let's stick to the basics (he says about an AI that has transformed the world).

Hold up

We can't just jump straight into coding. We wouldn't be very good project leads if we did.

For the best results, work with the AI in multiple, discrete steps and sessions:

1. Design a solution through conversation. Effective software development starts with a design. AI is great for bouncing ideas off of and helping you think out loud.

2. Implement tests based on business cases. I usually write tests during coding -- interwoven with my coding. In this case, I'm generating tests first, then using a different AI to write code to demonstrate the use cases of multiple AIs — also, because test-first development.

3. Write code in the IDE with AI plugins. We'll do this in an interesting way. I promise.

4. Fix the code by using the tests. Yes, you will need to fix the code. 

There's another reason to break this into multiple steps:

If you don't have GPT 4 access, 3.5 will work with more guidance from you.

To get the most out of GPT 4, split the load. 

• Use GPT 3.5 to help design and GPT 4 to generate code. GPT 3.5 is generally good enough at software design to tease out the details needed for a good design. If you can coach GPT 3.5 to develop a good design, you understand the problem well enough.

• Use GPT 4 to coach if you are working on your design skills, and then use GPT 3.5 for code.

• Split GPT 4 sessions to be able to use more than 25 messages. Handle design in one session and coding in another. 

• Ask ChatGPT to generate prompts to use with other AIs or AI sessions. For example, "generate a prompt to tell another AI what we just discussed."

Onward

This is the process we’ll follow:

1. Consult with ChatGPT to design a solution and generate a lightweight design document. We will use this as input for all the other steps.

2. ChatGPT will generate a PlantUML diagram from the design specification. This gives us a nice visual to put in our design document and lets us verify ChatGPT understands our design (us too).

3. ChatGPT will generate an OpenAPI spec from the design specification. We’ll feed this into other design components. Also, I like API-first development.

4. ChatGPT will generate tests from the design specification. It helps to pair this with the design document because good tests describe the business use cases of your software.

5. Switch to IDE.

6. CodeGPT will generate application code from the tests. Test-first development — this is the stuff of science fiction!

7. Pair with CodeGPT and CodeWhisperer to ensure the tests pass and verify the correct functionality.

8. Profit.

For the best results, don’t just say, “Write me code that does X”; use a prompt that:

• Clearly defines roles for you and the AI: "You and I are software engineers. We will use pair development."

• Sets a goal: "Our goal is to craft the best possible application to satisfy the design."

• Defines a process to follow: "We will follow this process: {bullet list of process}"

• Lets the AI ask questions: "You will ask me questions about assumptions until all your questions are answered."

Prompt frameworks make AI interactions more effective. They ensure clearer, relevant responses and save time. Frameworks maintain consistency, facilitate more straightforward data interpretation, and encourage effective learning. The #prompt-library channel in the OpenAPI Discord is a top resource.

Let’s move on to designing with AI.

The Scenario

We need an example to work with. AI is pretty great at leet code examples. I am not. Also, I said this would be a practical example. Leet code is not indicative of real-life work. 

For practical examples, it helps to use something similar to real-life work. 

• Coding Challenges is an excellent resource for building real-world applications. 

• A URL Shortener Challenge looks like a good, practical example to work with.

Next

Head to Part 2: Continue the journey.

• Part 1: Setup and Process ← YOU ARE HERE

• Part 2: Design

• Part 3: Sequence diagram and API specification

• Part 4: Generating tests

• Part 5: Generating the application and making it work

I've briefly mentioned ADRs before. They are great for maintaining transparency and intent by capturing the "who," "what," and "why" of decisions. Refer to the initial article for a deeper understanding of ADRs and their role in an autonomous architecture design framework.

I’ve set up an ADR Library to make it easier for everyone to adopt ADRs. This library of ADR templates can be used as a basis for your own decision records.

I will let the ADR below speak for itself on why a decision-making process is valuable and why to choose this one. Feel free to use this ADR as a template for adopting it with your team.

Below is the rendered version of the ADR. You can get the Markdown source for it and more in the ADR Library.

DACI for Decision-Making Process

• Status: accepted

• Driver: {who drives the decision}

• Approvers: {who approves the decision}

• Contributors: {whose input is sought (two-way communication)}

• Informed: {who is kept up-to-date on progress (one-way communication)}

DACI for Decision-Making Process

Context and Problem Statement

Our team is continuously seeking ways to refine our decision-making processes. We believe clearer roles and responsibilities in this process will enhance efficiency, minimize misunderstandings, and foster collaboration.

Decision Drivers

• Clarity of roles -- who is involved in making decisions and who is impacted.

• Simple -- must be easy to explain and understand.

Considered Options

• DACI

• RACI

• RAPID

Decision Outcome

We will adopt the DACI framework for our decision-making process. DACI stands for:

• Driver: Person driving the project and responsible for the decision-making process. This person should understand the project and facilitate communication among stakeholders.

• Approvers: Individual(s) with the final say. Typically, individuals in this role possess the authority to make decisions.

• Contributors: Those providing valuable input to the decision. Contributors can be anyone with relevant information or expertise.

• Informed: People who need to be aware of the decision once made. These could be team members impacted by the decision or other stakeholders.

At a minimum, we will apply DACI to:

1. Design Documents: To decide on the best design approach.

2. Any/Architectural Decision Records (ADRs): To drive decision-making for system-wide changes.

Pros and Cons of the Options

RACI

RACI stands for Responsible, Accountable, Consulted, and Informed. While it provides a similar structure to DACI, the difference in terms can sometimes lead to ambiguity, such as distinguishing between "Responsible" and "Accountable".

RAPID

RAPID stands for Recommend, Agree, Perform, Input, and Decide. This model emphasizes decision execution but can be overly complex, especially for smaller teams and less hierarchical organizations.

Consequences

Adopting DACI is expected to enhance our decision-making process, promoting clarity and efficiency. It requires a learning period and may necessitate adjustments in our workflows. Ultimately, it's anticipated to cultivate a more transparent and efficient environment.

More Information

Suggestions for Adoption

To migrate to DACI, we can:

1. Present: Conduct sessions to familiarize the team with DACI.

2. Implement Incrementally: Begin with one project and gradually expand its usage.

3. Regular Reviews: Schedule reviews to assess DACI effectiveness and make adjustments.

The Markdown source for this particular ADR is available here.