I get asked very frequently about my policy at Zid that we host exactly one intern/trainee at a time. The whole 6-month “batch” is one person. People at Zid and externally would say things like: why not have more? There are more people in the team who can coach. We need more capacity to work. Which are all valid thoughts, but they miss the context of what I am trying to achieve with these individuals.

I will discuss my perspective on the making of excellent engineers, which is a personal goal of mine that I have the virtue of being able to pursue as part of my job at Zid. One note before I get into it, the title might not be so accurate. I believe what I do would help push the person into the top 5% of engineers, but it is gonna be up to them to push themselves into the top 1%.

It mainly comes down to the fact that we are not a boot camp. Bootcamps admit people in relatively large batches, hoping that the majority will graduate with enough knowledge of the curriculum to secure a job. Output is consistent and predictable for both students and hiring companies. Every student more or less receives the same amount of attention and help, and they all go through the same material regardless of their background or competence.

We want to focus and personalize the experience for each individual’s needs and skills. Having a big class of interns means that a mentor’s attention would be divided among them. Each individual has different qualities and needs time in different areas. The mentor would either give generic feedback to everyone or put most time on a single individual, neglecting the rest.

One might ask what kind of attention I am referring to. The internship is not about getting a few small tasks assigned, then senior engineers give a few code review comments. That is just day-to-day work for anyone. I assign interns reading assignments in related areas where they need to read the chapter or paper, summarize it, and then object to it. This might sound like a school assignment, which I have to admit, it is. However, I choose topics that have direct applications and examples from our systems.

The point of this is that writing disciplines one’s thinking. When they have to articulate all the mess of ideas in their head, put them in writing, they have to be more thorough. The point of summarizing is to ensure that they charitably^[1] understand what the author is trying to convey, and do not jump to conclusions based on pre-conceived notions^[2]. Then the objection is to practice writing a well-articulated rationale, refining it, and defending it.

Reading, correcting, discussing, and objecting would all require time that cannot be divided reasonably across multiple people. Otherwise, feedback would be barely useful or would have minimal insight. Again, we are not a boot camp. We are not trying to be. We choose an individual and double down on our investment in them. Bootcamps try to graduate as many as possible who meet certain criteria.

So, what kind of individual am I looking for? I sum it up in two characteristics that influence everything else –Sharp and thorough. Sharp in the sense that they move fast. They get things without repetition and with minimal input. And thorough in that they go into details, they do not just take things at face value or only learn the big picture. Sharp and thorough people tend toalso be assholes. Some level of asshole-ness is acceptable, but there has to be a threshold^[3]. We still want people to be confident and take pride in their work. I discussed how I test this in my post Thoughts on Technical Interviews.

The other thing we look for, as defined in our role competencies, is being able to “demonstrate above peer average knowledge.” Meaning that we want Someone who already knows more than the basics in their field. Someone who, for example, knows how to build a web app, design a database, and architect a system. We do not want to start from nothing; we want someone who is okay (based on our measure), and we make them excellent.

I think one critical point that allows us to hold the bar so high is the strict rule against planning based on intern headcount. Interns are an “extra” capacity, a long-term investment. Leads and PMs are explicitly told to plan based on the full-time team members. And more importantly, we do not brag about the number of batches and quotas that we filled with interns. We do not think that this is something we should be chasing. These two reasons, combined, allow us to take our time interviewing tens of candidates and say no without fearing that we would miss a target.

By product of this competitiveness is exclusivity. I do make sure that every candidate understands the acceptance rate of the role, and the expectation out of them if they get the offer. I noticed that this exclusivity ensures that interns take their role seriously and want to succeed at it.

To sum it up, we do not need to hire interns; we choose to invest in them. We do not have a set program; we create a learning path for every individual to fill their gaps and capitalize on their interests. And lastly, look for the people who are sharp, thorough, and have above-peer knowledge.

I had previously written an internal memo about how I conduct technical interviews at Zid, which has sparked an interesting discussion. There, I mentioned that, in technical interviews, I do not necessarily specifically look for technical knowledge — that is, how much the candidate already knows. Instead, I look for how they would interact in a knowledge exchange setting. In other words, how would they react if someone taught them something or they taught someone something? How would they behave in a setting where they are the least knowledgeable person or the most knowledgeable person?

Here, I will expand on this thought and discuss what I would learn about a candidate depending on how they react during the interview. Keep in mind that the interview setting can affect the candidate, but I think given how informal we, at Zid, try to make them, this effect is negligible.

Now, in the interview, we do a design exercise where I present the candidate with a product idea and some constraints and ask them to guide me through their thought process to build such a system. Here, we get to our first road crossing. Some engineers would be paralyzed and ask me to guide them. Usually, their first question is: What do you mean? They want a set of well-defined questions for them to answer and not an open-ended prompt. These engineers are executor engineers. The team lead^[1] gives them clear instructions of what they want, and they execute^[2]. Other people would start answering immediately. They do not ask any clarifying questions. They just go! These would usually mess up and go all over the place, and I would have to stop them to reorient. The last group are ones who would explicitly state their assumptions (or ask for ones). They wouldn't start the design without ensuring they understand what they are getting into.

The candidate's attitude towards this exercise gives a glimpse of their leadership style and attitude. Some people will never make a decision on their own. They might come up with options but never decide. Others would recklessly make decisions. And there are those who make well-thought-out moves.

Also, this demonstrates how independent the candidate is. There is a difference between asking to understand the context to make a well-informed decision and asking to push the interlocutor to make the decision on your behalf. There is a balance to strike between assumption-making (based on context) and asking questions to be independent yet not naively reckless. If someone asks too many questions, they require too much babysitting. And if someone asks no questions, they do not know what they do not know. To be honest, I've yet to decide which one is worse.

Returning to the interview, we get to the more technical parts as we go through the discussion. This is where I get to assess the candidate's technical depth. In the previous parts, we mostly learned about their mindset and attitude. Here, I would ask the candidate to concretely specify how they would implement this system.

They should choose the programming language, framework, and data stores (yes, plural). The majority of people would suggest the stuff that they already know. They would choose the programming language and framework they are familiar with and one of the major relational databases (i.e., Postgresql or MySQL). A small minority would be adventurous and suggest tools they have never used but heard might be appropriate for their case.

To assess their understanding, I would do the following: If they chose the tools they know, I would suggest to them a different tool that could work just as well (or better) and see how they differ – if at all. Some would say they simply do not know, some would make stuff up to defend their original stand, and some would discuss how this suggestion would or wouldn't work, given the system constraints addressed earlier.

On the other hand, if they were adventurous, I would point out a known problem with the technology they chose to see if they really have a technical logic behind the choice or if it is just chasing the buzzwords. For example, I once interviewed an engineer who solved a query performance issue with Elasticsearch on the explore page of their app – note that this app did not have search functionality. I asked them why they did not use their existing Postgresql database with a few materialized^[3]. They said they did not think about this, which says much about this person's understanding of databases. If an engineer jumps to a new tool without fully exploiting their current ones, it indicates the depth they would take in solving problems (e.g., performance regressions are a very common example).

Circling back to my original point, all of these discussions should be viewed as knowledge exchange settings. Presenting a design is knowledge exchange, objecting to it is knowledge exchange, and defending it is knowledge exchange. Evaluating a knowledge worker should be based on this measure and not purely on what they already know. Nobody knows everything, and they are bound to learn something from someone. And at the same time, everyone will have to teach someone something at some point. So, their attitudes in these conditions will make all the difference in their success with the team and the organization.

I very often receive surprised-discontent faces from fellow engineers after I show them potential solutions to some highly contended problem in the team. It always turns out to be that they are not necessarily not convinced that this would solve the problem but rather surprised that the solution is simple. Their intuition tells them that simple means easy, and the problem at hand cannot be easy. Our engineering training that hard problems require complex solutions and have to involve a bunch of design patterns has made it difficult for our minds to accept a solution that does not utilize a few dozen concepts.

First, we have to understand, once again, that simplicity does not equal difficulty and that simplicity IS hard. Getting to a simple solution requires multiple iterations over multiple complex solutions and digging deeper into the problem to simplify the design. The more you understand the problem, the simpler your solution will be. It goes the other way, too. Usually, when I see a very complex solution, it indicates that this engineer does not understand the problem well enough.

I should define my view of simplicity for the purposes of this discussion. A simple system is a system that can be understood by anyone with minimal domain knowledge^[1]. In my opinion, more engineering is less business^[2]. If you start from the technical aspect, you cloud your view of the business aspect. Why? Because you will try to look at the business from the lens of design patterns and SQL schemas. You will be trying to forcefully fit the business into the boxes of the few design patterns you have present mentally, which tends to complicate things, and not get the boxes and try to fit the use cases in them.

On the topic of design patterns, the most crucial part of design patterns is the patterns, not the design. Design patterns are solutions for common problems and not common solutions for problems. You need to find the problem first and then use the design. It is all about finding problem pattern ^[3]. I usually refrain from teaching design patterns to beginners (or even mid-level engineers) and prefer to teach them to come up with similar solutions on their own, which helps them to set up their mindsets to start with the problem, not the solution.

Despite this rant about design patterns and simplicity, why are engineers not satisfied with a simple design when someone else comes up with one? I call this the dilemma of pride and engineering complexity. It would not sound as cool to say I solved a problem with a few if statements in a Python file compared to saying I solved it by implementing an event-driven system in half a dozen micro-services.

However, on the contrary, it is more challenging to come up with a simple solution. It is always much easier to complicate things. A little misunderstanding here and there can go a long way in complicating your design. Simple designs are what we should be proud of because unimpressive simplicity is quite impressive.

Philosophy and engineering are two subjects that can be viewed as two different worlds. Unrelated and of no use to each other. Philosophy is theoretical in its investigation, and engineering is an extremely practical discipline. In this write-up, I claim that these two fields have more in common than one might think and that learning philosophy helps make an engineer more thorough.

Note that I will usually use the term engineer to refer to a software engineer. Although, the first and weaker claim can be extended to most engineering disciplines.

What Do I Mean by Philosophy?

Philosophy can mean different things to different people – for more on this, refer to the first section in my write-up on philosophy and programmers. For our purposes, we will distinguish between philosophy as a discipline and philosophical thinking as the thought process involved in tackling problems. Philosophy as a discipline or a field of study has different branches that examine knowledge, language, logic, ethics, and science. Philosophical thinking is the general capacity to ponder and examine things in a systematic approach. I may use the term philosophy to refer to philosophical thinking in some sections of this discussion.

Okay, You're Saying Logic

Engineers are trained to be analytical and logical in their thinking. I took logic in school and did plenty of math. Yet, that is not enough because, in engineering, there is always a system that you work within. It is unusual to challenge that system – that does happen and may lead to great outcomes, but rather rare.

In philosophy, however, it is almost always about challenging the system, if you had one at all.

Philosophy Is a Logic Exercise

Philosophy discusses difficult and seemly unsolvable questions in almost every area of knowledge. Questions that challenge preconceived notions and challenge "common sense" lead people to come up with all kinds of creative solutions. Sometimes the solution is not to answer the question but to redefine the question.

One philosophical problem that we can draw direct parallels to engineering is the barber's paradox. Barber's paradox asks us to imagine a town with a law that requires all men to be cleanly shaved. And says that the barber shaves only the men that do not shave themselves. In other words, all the men who do not shave themselves have to go to the barber. Otherwise, they will have to shave themselves. The question here is, who shaves the barber? If the barber shaves himself, then he does not go to the barber (that is himself). And if the barber does not shave himself, then he has to go to the barber (also himself). Both cases are contradictions.

Ignoring the mathematical roots of the paradox, this puzzle shows an example of a system design that sets the conditions you will have to operate in, which may make some tasks impossible to accomplish. The constraints that our system had set made finding the "shaving behavior" of the barber non-deterministic. It could be any of the two conditions; it is up to the implementer. Imagine having a language spec with a similar constraint, and it is up to the compiler maintainers to choose a behavior – we have many examples of this with the C compilers.

You might say this is a mathematical puzzle, not really philosophy, so I will give another example. However, this time I will take the other direction. I will give an example in engineering that maps to philosophy. This time, I will talk about my approach to debugging. I call it skeptic debugging.

Skeptic debugging is to assume that nothing is working in your application and then start building your confidence layer by layer, which means if I start by assuming that my application is broken to the point where it fails to boot. I start by ensuring it boots, then confirm that I can navigate to the page where the faulty feature is, and so on, until I find the point where my expectations are not met.

Skeptic debugging is a bottom-up approach as opposed to the top-down approach where you would jump into where the feature is and try to mess around until you get sick of it and then realize that nothing is wrong here, but it is the layer below that is broken.

I think skeptic debugging, as the name implies, directly maps to the skepticism (precisely, cartesian skepticism) in the philosophy of knowledge or epistemology. That is the process of validating one's beliefs, starting from the most foundational beliefs one has.

Philosophy Directly Influences Engineering Decisions

Some fields of philosophy have immediate implications on how we approach engineering, and in some cases, philosophy might obligate you not to do engineering – as in some ethical dilemmas.

Let us start with ethics. Ethics (or moral philosophy) is the study of what makes an act right or wrong and how we decide what is valuable. Value theory studies the why, how, and to what extent humans should value anything (including a person, a concept, or an object). This is crucial when designing any kind of autonomous robots, especially autonomous vehicles where we have to design robots to make decisions in some variants of the trolly problems. In the trolly problem, the vehicle is the agent having to decide whether, for example, to prioritize the safety of its passengers, another vehicle's, or the pedestrians'.

Another example is the philosophy of language. Philosophy of language studies how language is used and how it is understood. This is the root of natural language processing in computing. Natural language processing (NLP) tries to understand the user's language and tries to produce utterances in response. NLP specialists have been trying to model human languages in structures that computers could then interpret, attempts that have followed language philosophers like Chomsky's Syntactic Structures. There is also a paper titled Wittgenstein’s Philosophy of Language The Philosophical Origins of Modern NLP Thinking, that I think is a great resource to get a further picture of how philosophical understanding of human language has influenced computational understanding.

How Do I Start?

Philosophy is a skill that can be acquired by reading a few books or even dozens of them. Philosophy's core values are acquired through challenging the ideas. Take an idea, and try to understand it very well to the point where you know where it fails to achieve a certain goal and object to it. You may ultimately agree with the end result, but you can object to the reasoning that led to this result. It is all about learning to grasp ideas and challenge them systematically.

One approach that I think is helpful to get started is to find a reading partner or, better yet, partners – the optimal size is 3 to 5 at most. You decide on a reading passage as a group, read it, and then come prepared to explain it to each other and critique it. It may be helpful at the beginning for each one to research how other philosophers have objected to the selected passage. For some more difficult passages, you may also need to research how others have interpreted the text to aid you in understanding it before heading to the discussion.

Now, the question is, where do we get these topics and passages from? I recommend starting with a history of philosophy book^[1]. These books usually provide an overview of the philosophical problems that have risen throughout history (usually up to the 1900s). Then you choose one of the topics to dive deeper into. But now, how do you find the texts for that topic? Once you know the topic, you can look for college courses' syllabi. Colleges post these publically and would usually include the readings for the course.

"All problems in computer science can be solved by another level of indirection" (Butler Lampson).

I think this quote clearly presents how crucial abstractions are as a tool for solving computer problems. However, as important as this topic is, we do not see proper attention drawn to it when training engineers. Yes, there are a few books (e.g., Clean Code by Robert Martin) and many blog posts, but these usually focus on the technicalities (that is, how to write the code) rather than the thinking and mindset orientation. My goal here is to have a comprehensive discussion of what the engineer should be thinking about before and during the process of designing the abstraction. In other words, in my discussion, code is just a demonstration tool rather than the subject of the discussion.

Before we get started, I highly recommend reading Stripe's post on the first 10 years of Stripe's payments APIs. It tells a story of the natural progression of a software business and how its offering has grown, and so has the complexity of its abstractions. Their case is unique because their main product is APIs, so changes in the abstractions are more prominent. I will be referring to it as it has a few great examples of most of the ideas that I will discuss.

Defining the Units of Abstraction

By units of abstraction, I mean what we should expect our users to know and what we expect them never to have to know. This is defining the inputs and outputs of the abstraction. An example of this is Stripe's PaymentIntent API. They expect the API user to learn about a few Stripe objects like Customer, PaymentMethods, and PaymentIntents themselves to be able to use the API. Then, internally they abstract away the complexity of handling the API. They do not expect their API user to know how they store customer info or how they integrate with networks. And this is an intentional design decision.

Another example, this time from a micro perspective, is at ZidShip, we had a balance management service. The engineer working on it was suggesting to implement updating the balance as follows (written in Python and Django):

package = merchant.packages.select_for_update().get_active_package()
if package:
    if package.balance_remaining <= 0:
        raise Exception("Insufficient package balance")
    package.balance_remaining = F('balance_remaining') - 1
    package.save()

This will select the active package for update, then check if it's not null, ensure it has balance, and then deduct 1 from it.

I had a few comments on this design. One, the user needs to know the inner workings of the package and be careful to check the balance. Two, the select_for_update part is easy to miss, and I am worried that one might forget to add it and cause a race condition. So, I asked the engineer to try to abstract it.

The engineer's intent was to make it explicit, specifically, the select_for_update. They wanted to make sure that the user of the packages API is aware that they are locking the row when they do it.

That is valid; however, they were not thinking about their units of abstraction. What this engineer had in mind was abstracting loading the packages, but what I suggested was abstracting all balance manipulation. That is, make an abstraction layer that takes the merchant and how much you want to deduct or add to their balance. In other words, we are abstracting the whole snippet as follows:

def deduct_balance(merchant, amount):
    package = merchant.packages.select_for_update().get_active_package()
    
    if not package:
        raise Exception("Merchant has no active packages")
    
    if package.balance_remaining <= 0:
        raise Exception("Insufficient package balance")
   
    package.balance_remaining = F('balance_remaining') - amount
    package.save()

Now, every call site would only need to know two things, the merchant and how any units (i.e., the amount) we want to deduct. Then loading and locking the row is centralized. And we added a new case for handling merchants that do not have active packages.

Why is this better? First, all operations done on balance HAVE to be atomic and would require locking the row, so this way, we avoid forgetting to select for update. Second, users of the API would require so much less context to be able to interact with the balance. Meaning they will not need to learn about active and inactive packages or how these packages are purchased and activated.

You can see how defining the units is crucial on all levels, whether designing an API with a few hundred endpoints, like Stripe's or even implementing a 10-line function to help you avoid all sorts of nasty race conditions.

Understanding the Dimensions of the Abstraction

This is where we define what I call the depth and breadth of the abstraction. The wider the abstraction, the more use cases it has, and the deeper it is, the more layers it hides. Exploring these dimensions gives you clarity of the boundaries of your scope. Two common traps that engineers fall through are what I call abstraction bloating and pass-through abstractions.

Abstraction bloating happens when you try to incorporate too many use cases into your units of abstraction. In dimensions terms, the abstraction is too wide. Going back to Stripe's example, their team tried to force their original credit card (Charges) abstraction to do too much. Charges API was designed to handle immediately finalized payments that did not require customer action, and then they had to break one or both of these conditions. This an example of both working on the wrong units of abstraction and bloating it at the same time.

Another case of bloating is Django rest framework(DRF)'s serializers. Serializers in most other contexts convert objects from the language's native format to a format that can be transmitted elsewhere (e.g., python object to json). However, DRF's serializers do more than that. They handle data validation and state manipulation (i.e., save and update methods). For those who never used DRF, this is a sample serializer for a user model adapted from DRF's docs.

class UserSerializer(serializers.Serializer):
    email = serializers.EmailField()
    username = serializers.CharField(max_length=100)
    
    def create(self, validated_data):
        return User(**validated_data)

    def update(self, instance, validated_data):
      ...

This converts User objects to json, validates and parses json into User objects, and manages the state in the create and update methods. In this design, the serializers do too much and can be confusing and hard to learn. Yet, some might argue that this abstraction is appropriate. The DRF maintainers were thinking about making fully functional units that, once mastered, could be used to quickly implement the majority of use cases. I will be discussing this idea further in the next section.

A pass-through abstraction is an abstraction that does not hide any complexity. It assumes too much knowledge from its user. It occurs when you do not consider the depth of the abstraction. You may recognize this as "shallow abstraction," but I will refer to it as pass-through for my purposes. A very famous example of this is the Java I/O library. I think most of us had to use this library at some point. I can never write any I/O code in Java from my memory. The library exposes too much complexity to the developer. For example, to read a file, you must know the difference between a File, FileDescriptor, FileReader, BufferedReader, and a Scanner. The library has different sets of abstractions for parsing versus reading a file, even though parsing can be a subset of reading. With this many concepts, it would not be much different from calling the lower-level APIs directly. Hence, a pass-through abstraction.

Start and End With the User in Mind

It is easy to get caught up in the implementation of the abstraction and forget the user. This is where the abstraction starts leaking. Ideally, the designer of the abstraction should think from the user's perspective. Think about the common use cases and how concentrated or scattered they are. Always make the most common use case the easiest.

I usually do this by laying out the use cases, starting with the simplest (not necessarily the most common) and then expanding the design based on what needs to be changed for each new use case. For example, let's say I am writing a function to upload files to S3. The files can be either public or private. Private files can be accessed through signed urls that have an expiration date.

I would do this in three phases. First, consider the simplest case, which is uploading a public file. Then, add support for private files. Lastly, add support for signed urls. So, our interface for the first case would be something like this:

def upload_to_s3(file: IO, key: str):
		pass

We take any IO-compatible object and the key (the path in S3 terms). Then, we expand to support private files by simply adding an is_private parameter like so:

def upload_to_s3(file: IO, key: str, is_private=True):
		pass

Notice that I am setting the default to True because it turns out that, in most cases, we need to upload the files not to be publicly viewable. And we do not want our engineers to accidentally upload a file publicly, so we make that use case the default. We are making uploading a public file an active choice.

Now, we want to support signed url generation. So, we add two new parameters for that, generate_link, and link_expiration. generate_link decides whether or not to generate the link and link_expiration specifics how long (in seconds) this link should be available before it expires.

def upload_to_s3(
		file: IO,
		key: str,
		is_private=True,
		generate_link=False,
		link_expiration=604800,
):
		pass

Again, we are adding defaults to keep the most common case the easiest. So by default, we will not generate a link and will ignore the expiration parameter. And if the generate_link parameter is enabled, we will generate a link with the specified expiration.

Now, notice how we are hiding all complexity of S3 and which buckets are used for which files. There are no S3-specific parameters passed to the function. We can even swap S3 for a different storage backend, for that matter. These are all part of the abstraction. Users of this function who need to upload a private file with a signed link should not have to actively think about which bucket they are uploading to and what permissions should be assigned to the file. These are all implementation details and do not contribute to the user's business value.

Going back to the Java example, I think the Java IO library fails to make the most common use case easy. It focuses so much on purity rather than usability. The most common use case there is reading a local file as a whole or line by line. And for the majority of these cases, using a buffered reader is most optimal. So, these should be our defaults. I would leave designing a better API for this in Java as an exercise for the reader.

And for Stripe, this is exactly what they were excelling at. They made the common case so easy to implement and start someone might even argue that this made them complicate the less common case.

Allow Your Users to Escape Your Abstraction

The whole point of abstractions is to make a certain job easier. Sometimes that job is not exactly what the abstraction designer intended or assumed, which is not necessarily bad. Actually, more often than not is a good sign. The abstraction has proven useful, and its use cases have expanded.

The difficulty here is that designers sometimes intentionally lock down their abstractions, so they cannot be expanded. That could happen due to a few design decisions.

First, building the whole abstraction as one unit or layer where the user cannot use any lower levels of the abstractions to expand the use cases. Let's go back to our S3 upload example and assume that some user wants to generate signed urls for a pre-existing file. Maybe the original url has expired, or they might have never generated one in the first place. If we implemented the logic directly in upload_to_s3, that user would not be able to utilize our abstraction. A better approach would be to extract the link generation logic into a separate function. Like so:

def upload_to_s3(
		file: IO,
		key: str,
		is_private=True,
		generate_link=False,
		link_expiration=604800,
):
	  # Upload logic
		if generate_link:
        return generate_signed_s3_url(key, link_expiration)
        
def generate_signed_s3_url(key, link_expiration=604800):
    pass

Yes, this seems obvious and straightforward, but I have seen this so often that I had to show such a simple case.

The second category of design decisions that prevent the user from escaping the abstraction is mainly caused by object-oriented programming (OOP). I believe pushing engineers to be OOP purists leads to designs like Java's IO library. One OOP that I want to focus on is member visibility. For 90% of the cases, all class members should be public. I would go as far as to say that static analysis tools should have a check for preventing engineers from hiding class members. The reason is that it is common to find a method that does almost the thing you want, but not exactly, so I would copy the method's implementation and change what I need elsewhere. However, I cannot do that if all the members that the method uses are hidden (either private or protected).

One might say that "Just make a subclass and override it." Well, one, that is a new pass-through abstraction. Two, that is not doable if the method I am overriding is private. And three, it is very common that you are trying to debug something in the shell (or maybe running a one-time script), and you want to go through some method and run it line by line, but you cannot do that because members are hidden.

I can go on for hours with more reasons why defaulting to hiding members is a bad practice, but I will stop here. The only case where I think hidden class members make sense is in systems programming, where you want to deliberately prevent the abstraction users from tampering with some state or a resource because that could lead to a series of undefined behaviors. Yet, even then, I would carefully decide what should be hidden and try to leave as much of the interface public as possible.

Closing Remarks

I am only scratching the surface of the considerations that go into designing abstractions. There are many other tradeoffs that should be considered, including the software design questions that I have previously introduced in a separate post.

In the previous article, I introduced the software design questions and gave some scattered examples of the various questions. In this article, I will present a fictional business and try to apply the questions on it as a practical example.

Before I begin, I would like to thank Atheer Alfawaz for her suggestion of the business idea and for workshopping this post with me.

Our business is going to be a gig economy-based vehicle services platform. We will expand on the details in the next section.

The Business Context

Here, we will answer the following four questions: What do we do? Who are we serving? What is our goal? How are we trying to reach it?

What do we do? We connect service providers to customers.

Who are we serving? For our first iteration of the products, we will only provide non-urgent car services (e.g., car wash, oil change, etc.). So, the assumption is that our customers are going to be med-to-high-income car owners, and they will book beforehand.

What is our goal? To be an all-in-one vehicle services platform.

How are we trying to reach it? Our first iteration will focus on providing non-urgent car services like car wash and changing engine oil. We will have two types of services: at-home and in-store.

Design Cycle

Before I start proposing designs, I want to explain our procedure to doing that. I call this procedure: the sketch, mock, evaluate, enhance, and iterate cycle.

In this sketching step, we will write down our current conception of the system – we will specifically focus on the data model. Then, the mocking steps involve testing our design against assumed business use cases (including near-future ones). Then, we evaluate if this design is good enough or lacking. Also, this is where we evaluate the complexity of our design. If it is lacking or too complex, we will proceed to the enhancement step. Here, we may add to our design, remove something from our design, or even start from scratch. And we start over.

First iteration

Our main entities are going to be Provider, Customer, Service, and Request.

Sketch

So, my first iteration of the data model would be as follows:

• Service:

  • Name
  • Category
  • Description
  • Price? <– Keep this one in mind

• Provider:

  • Name
  • Description
  • Services (from the Service entity)
    • type: in-store/at-home
    • Price?

• Customer:

  • Name
  • Phone number
  • Location

• Request:

  • Service
  • Provider

Now, we have a question that we need to ask ourselves. Should the price be set per service or per provider per service? And this is where we go back to discussing with the product managers to make our first tradeoff. Are we letting providers set their own prices, or are we setting one price for each service? If we were to let the providers set their own prices, what would we do when we get to on-demand services (remember, our first iteration is non-urgent services)? We ask that because our vision is to become an all-in-one vehicle services platform, so we need to ensure that we do not shoot ourselves in the foot. This is a tradeoff between flexibility and consistency.

Also, from a business perspective: if providers got used to being able to set their own prices, would later enforcing a fixed price be perceived positively?

Let's say we decided to let them set their prices, and this marks our first baking assumption. Our design would be like so:

• Service:

  • Name
  • Category
  • Description

• Provider:

  • Name
  • Description
  • Services (from the Service entity)
    • type: in-store/at-home
    • Price

• Customer:

  • Name
  • Phone number
  • Location

• Request:

  • Service
  • Provider

Mock

We have the following business questions inferred from the assumed UI and flow:

• What are the available providers of a certain service at home?
• Who are the busy providers?

Evaluate

Now, does this design answer our mock questions? For the first one, we can filter the list of services at-home and list the providers. That could work, but "available" means that they are not busy at the moment. Meaning, we need to tell if they are busy and remove them from the available list. Our current design does not support that. And that is also the same issue we will face with the second question.

Enhance

To fix our issue, we need to add two things a booking time and a status. Status can be: initiated, in progress, completed, or canceled. So the Request would look something like this:

Request:

• Service
• Provider
• Status
• Booking Time

But if we read a little bit into the future. We realize that we can tell who is busy but not how long they would be. So, we need to also add an "average" booking duration in each service.

Second Iteration

After the three enhancements added in our last iteration, our new sketch would look as follows:

Sketch

• Service:

  • Name
  • Category
  • Description

• Provider:

  • Name
  • Description
  • Services (from the Service entity)
    • type: in-store/at-home
    • Price
    • Duration

• Customer:

  • Name
  • Phone number
  • Location

• Request:

  • Service
  • Provider
  • Status
  • Booking Time

Mock

We will keep our previous two questions, and we will add the following:

• When will a certain provider be free?
• What are all the requests of customer x?

Evaluate

For our original two questions, we now can tell who's available based on booking times and their service type. Likewise, we can use the booking times to see who's currently busy. For the two new cases, the first question is easy. We can, again, use the booking time and add it to our average service duration. As for our last question, this is something that seems like we overlooked. Our Request entity does not have a customer :)

Enhance

This time we will simply link our requests to their customers by adding a customer to the Request, like so:

Request:

• Service
• Provider
• Customer
• Status
• Booking Time

Final Design

• Service:

  • Name
  • Category
  • Description

• Provider:

  • Name
  • Description
  • Services (from the Service entity)
    • type: in-store/at-home
    • Price
    • Duration

• Customer:

  • Name
  • Phone number
  • Location

• Request:

  • Service
  • Provider
  • Customer
  • Status
  • Booking Time

Note that it is "final" in the sense that we would build this, but it does not mean we will not change it. New cases may come up that would make us go back to the drawing board and start over with this design.

Some Pointers

• Try to keep your designs as small as possible (that usually corresponds to being simple), and add to them as needed. Removing is generally more challenging than adding.
• Stay away from database jargon – that is not what we are designing for at this step. Notice that I have not mentioned anything about databases. Yet, this design can mostly map nicely to your database schema.

Exercise Questions

I will add more mock questions to challenge the design and leave it to you to improve the design based on these questions.

• Can a provider serve multiple customers simultaneously (e.g., car wash stations)? How can we limit the number of customers?
• What are the working hours of a provider?
• What is the coverage of at-home services (i.e., what areas are served by a provider)?

Last year, I published a collection of discussions on software design where I discussed a set of central principles that should be considered while designing software. Here, I move to a meta-discussion about what questions you should ask when trying to apply those principles. If you have not read the first post, that is okay. It is not required to understand this discussion so you can read the posts in any order. You only need to know from that post the definitions of a system and software design. Software design is the process of managing tradeoffs when architecting a system. And a system in this definition can range from a single process/thread program to a multi-cluster, multi-region distributed system.

I want to start with what this write-up is not. This is not a step-by-step manual on how to design scalable and simple systems. I believe that software design is part knowledge, part art, and part experience. I also want to emphasize that no matter how good the design is, it is bound to have some shortcomings. So, the goal is not to eliminate those shortcomings but rather to minimize their blast radius when we run into them.

This write-up is not going to answer questions but instead going to raise many of them. It is meant to help a designer ask the right questions to help them make more educated tradeoffs. Remember, software design is all about making tradeoffs, and making tradeoffs is all about asking the right questions.

I will discuss high-level and low-level ideas simultaneously, so some sections may be purely conceptual, and others may contain code snippets (in Python).

Learning the context

The first step in every software design project is to learn the context in which you are working. I have discussed this more thoroughly in a previous post, but I will summarize it in four main questions and expand a little: What do we do? Who are we serving? What is our goal? How are we trying to reach it?

The first question tells you the business line. So, for example, what we do at Zid is e-commerce. Now, the specifics of that come out of the following three questions.

The second question tells you who your customers are. This is where you specify your customer persona or personas. Keep in mind that if your answer to this question is "everyone," it means that you are doing something wrong. If you do not know who your customer is, assume one, do not try to serve all humans all at once.

The third question directs your efforts. It is the "mission" of your business. Answering it should tell you what benefits your customers are gaining from your business, which sets your compass for what solutions you should be looking at. For example, when Zid started, we used to say that our goal was to provide an all-in-one e-commerce platform. However, we now believe that we empower retailers to grow their businesses. That change gave us a dramatically different answer to the next question, as I will show with Uber.

The last question dives into details of your offering, and it builds on your answer to the previous question. Answering this question will determine the kind of solution you will build. For example, Uber's mission is "to help people go anywhere and get anything," they achieve that by offering a ride-hailing service and an on-demand delivery service. Previously, it was "make transportation as reliable as running water, everywhere, for everyone," which primarily focused on ride-hailing, and that is it. Now, Uber shows you all kinds of transportation methods buses, bikes, scooters, and cars (including rentals).

The two most important questions in software design

After learning the business context and background, we can now ask the core questions for our specific project. What are we optimizing for? What can we sacrifice?

We can optimize and sacrifice all sorts of values like performance, time to market, scalability, extensibility, user experience, developer velocity, developer experience, etc.

Any project should have some combination of these. Things you are optimizing for and things you can sacrifice. This decision should be intentional and explicit. For instance, if you are optimizing for time to market, you will have to sacrifice either performance or code quality – maybe a combination of both.

Some sacrifices can be unintentional (or, in a sense, incidental or byproducts), but optimizations cannot be (otherwise, we do not know what we're doing). For example, say you are sacrificing code quality (maybe, you are planning a rewrite if this takes off). You may have to sacrifice performance in the same places because the cleaner version is also more performant, but it will take longer to build.

Priorities do change, so you need to be prepared. Do not bake your assumptions into too many levels of your system.

class InvalidPlan(ValidationError):
  pass

def validate_plan(user: dict):
	if user["plan"] != "pro"
  	raise InvalidPlan()
  return input

def perform_billing(user: dict):
  if user["plan"] != "pro"  # This is a code smell
  	raise InvalidPlan()
  # Do billing logic
  
def bill_user():
  validate_plan(user)
  perform_billing(user)

Your logic should not be too coupled with your input validation. In our example, performing billing should not check for the plan. What if you wanted to change/remove that check? You would have to run through your whole codebase. Imagine changing it in some places, but not all of them. You would start to encounter the weirdest behaviors in your system.

Note On Sacrificing Extensibility

You may sometimes have to trade extensibility (for simplicity or delivery time), which means that you are making a particular assumption and sticking to it. For that, we need to understand the two kinds of assumptions: Baking assumptions and topping assumptions. Baking assumptions are the assumptions that if you were to change them, you would have to significantly rework the system. You can usually spot them when deciding whether to use a one-to-one or a one-to-many relationship. Topping assumptions are the ones that may only require a couple of lines of code to change—for example, changing from a sequential transaction number to a random transaction number.

Remember: do not shoot yourself in the foot. Do not bake a contested assumption. If there is a debate on whether an assumption is the right one for the long run, avoid baking it into your design.

What technology should I use?

Simply use whatever you know unless you know you shouldn't use it. This could also be seen as some sort of a tradeoff. You are optimizing for business, not technology "coolness." Do you want to build a business or build something with new shiny technology? It is a decision that needs to be made.

Organizational Context

Here, we need to understand the team (or teams) working on our software. What is the smallest team unit size? How much freedom does this unit have? To whom do they report? If this unit messed up, who is supposed to fix the problem? Is anyone going to be blamed? And how is your expertise distributed?

For example, if your teams are small (for some measure of "small") and autonomous (that is, they make all kinds of product and tech decisions themselves), a micro-services architecture (yes, it only took me about a thousand words to mention it) is most probably appropriate. However, if your teams are either too large or very interconnected, a micro-services architecture will become the mega-mess architecture.

One case where interconnection can happen is when only a few experts have a high concentration of knowledge about the system. That means they have to participate in almost every change – teams are not autonomous.

And as a side note for the previous example, this is one area where it is common for some people just to follow the trend and want to say that they implemented * insert buzzword * solution at their organization. And part of the community will be going around preaching about this architecture and how it solved their life problem, but they also need to share their organizational context (in what kind of organization was this architecture helpful). Some organizations are inherently slow, not because of technology but because of internal procedures. So implementing X architecture or X methodology will not help. It may make things worse. Remember Conway's law (yes, I had to bring that up).

Design Documentation

Now that we have learned our business context, specified our tradeoffs, chosen our technology, and considered our organizational context, how do we get this into writing? And how do we communicate it?

Unlike most of the previously introduced questions, I have a definitive answer here. You may have heard of class diagrams, use-case diagrams, sequence diagrams, etc. If you have, do not use them. These are unnecessary formalism that does not add to the conversation. On the contrary, they make it harder for people to learn all the modeling terminology and tools involved in producing those diagrams.

A simpler approach is to use informal diagrams and supplement them with textual descriptions with minimal usage of context-specific jargon. This way, you can onboard anyone to your documents by simply providing a glossary section that describes all the terminology used throughout the document – no external resource needed.

Deployed! What now?

Start over. Software design is not a linear procedure. It is a feedback loop. As the software is used, we learn more about its and users' behavior. Shifting our understanding of the business context and the tradeoffs we made – taking us to the first two sections.

"Hmm, Philosophy and Computer Science. An Interesting combination" is a very common response when I tell people I work in computing and am interested in philosophy. It seems like there is a perception about working in computing that a technologist is a person that would only be interested in STEM-adjacent fields; that a very human-centered area like philosophy is not for them.

I believe these are but a few of many misconceptions about being in tech. They not only affect how non-technologists perceive technologists, but they also affect how technologists view themselves. In this short write-up, I will give examples of how technology (mainly software) intersects with many areas of philosophy and how beneficial it is to learn from that.

What is philosophy?

This is an important question to answer before proceeding as philosophy can mean many things to different people. Some think of philosophy as "style" or the way they do things. Others think of philosophy as metaphysics or maybe how it relates to theology (and maybe to some, the antithesis of theology). Lastly, philosophy may be seen as merely the study of ethics in the most abstract and hard-to-come-by situations.

And these are all, more or less, parts of philosophy. Even amongst philosophers, there is this stereotypical categorization of philosophers as analytical philosophers or continental philosophers. Analytical philosophers are more interested in the rigorous math-like study, and continental philosophers focus on big picture theory.

Here, I use philosophy to refer to two intertwined ideas. First, I used it to refer to logic, epistemology, ethics, and the formal approach to theory formulation. Also, philosophy is the study of studying, the approach by which we examine things.

This specific approach to defining philosophy may not completely align with some of the academic definitions, but it serves a practical purpose here.

Logic

Logic may be the easiest of the bunch to relate to technology as it is the foundation of our work. We use logic to build our software. Boolean logic is the most fundamental building block that computers are constructed on top of. Yet, most programmers are never exposed to general forms of logic. That is thinking logically outside the realm of discrete input and discrete outputs that is practiced in computational logic.

Deductive and inductive logics involving decomposing human utterances to make inferences and drawing conclusions are essential tools for anyone building systems. This can be seen at work all the time with product managers and business analysts. They translate people's needs specified as premises in natural language to formal definitions in a restricted language (which occasionally includes diagrams).

As for developers, building systems is what we do every day. Eventually, the developer will have to make decisions based on the problem statement that was not explicitly defined in the requirements document. Especially since these documents greatly vary in their depth and detail. Some details will be omitted, and the developer will have to deal with them. So, having a logic background allows you to deduce implicit requirements from the business context.

Epistemology

Epistemology is the study of knowledge. What it means to know, believe, and the rational relation of knowledge and belief. Epistemology asks questions like: is it rational to believe in proposition x? Given that it is rational, does that belief constitute knowledge?

As a developer, I use epistemology whenever I am debugging a piece of code. I always tell my colleagues to be skeptics. Assume that nothing works, and then start rebuilding your confidence in what you thought was working piece by piece.

Epistemology also examines language and how it affects our knowledge or our perception of knowledge. Knowledge can also be context-dependent. I may know something in one context, but not in another. In that same sense, when writing code, we look into what context we have, what we know about our problem, and what we can infer. Then we structure our code to cover all of these branches of related sub-cases of the problem.

Ethics

I believe ethics has two folds in this matter. First is the study of applied ethics as a way to systematically evaluate our actions (and consequently, our software's). Second, the mode of thinking involved in studying ethics. That is having to decide what to value most and what to dismiss in evaluating decisions.

As previously discussed, we, programmers, love systems and patterns. The study of ethics tries to build what is called an ethical theory. That is a general system that can solve ethical dilemmas. Obviously, we are yet to develop one theory to rule them all. It is all about tradeoffs and what to prioritize. Similarly, when we design systems, we make tradeoffs. We build systems that serve certain use cases better than others because it is practically impossible to excel in all.

We also have ethics of computing where we discuss the moral considerations of our code. Considerations like bias, privacy, and autonomy are all at the center of such philosophical discussion. We see algorithmic bias in facial recognition, determining credit limits, and predictive policing.

Also, ethics has some gray areas. Some are situations where the ethical theory would suggest something that the agent (the person acting) may not be as confident to do that action because of common sense. In software, we deal with unexpected behaviors. Cases where we think our algorithms should act in certain ways, but given some set of input, we get an unintended output.

Language

Philosophy of language studies the nature of language, the use of language, and language cognition. Such investigation can directly benefit technologists working with Natural Language Processing (NLP). NLP is especially an area of human-centric nature. You can build the models through purely statistical methods, but you need to approach the evaluation of your NLP models from a user's perspective. You need to be aware of how people use language to be able to understand and produce language.

Closing Note

I can confidently say that Philosophy made me a better engineer and a better tech lead. Keep in mind that I only touched upon the direct parallels of philosophy and technology in this write-up. There is a lot more to gain from practicing philosophical thinking. Philosophical thinking pushes you to think of a problem in all directions and perspectives, allowing you to develop unforeseen solutions.

Lastly, I omitted the philosophy of science, yes this is a thing, because this field on its own can have a write-up of this size to explain how important it is to technology. It discusses the scientific methods, their effectiveness, and implications of scientific findings. And one deep area it investigates is Artificial Intelligence, the mechanization of reasoning, and regulating Artificial Intelligence.

This post might be a little deviant from my usual tech-focused blogging, but I think it's still relevant to tech—especially the abstraction section of my previous post.

The concept of abstraction is all around us. We may not actively think about it, but if we put on our analytical lens for a day, we will be surprised by how much we deploy this concept in our thought, craft, and technology.

I define abstraction as the process of hiding the details or focusing on what really matters. Here, I will present a collection of reflections and examples of fields that use abstractions in multiple similar yet seemingly different ways.

Philosophy

Abstraction is defined as the thought process wherein ideas are distanced from objects. Abstract is the opposite of concrete. If we think of a physical object like a book or chair, it is concrete. If we think of the concept of writing, this is abstract.

Let's take, for example, the common phrase "A cat is on a mat." If I asked you to imagine that, you would probably imagine any random cat you could remember sitting on any random mat you can remember. And that is what I usually want to happen. In most cases, the breed of the cat, and the material of the mat, for example, are negligible details of the idea I am trying to convey or discuss.

This nature of abstraction is very powerful. It allows us to think of the same concept but with different mental depictions of it. What may make you want to say it's the same but different.

In logic, this is utilized to build formal systems. A formal system builds a theoretical organization of objects based on implicit relationships using a set of rules. For example, in number systems, sets are used to categorize values, and rules are used to define how values are constructed and manipulated.

Art

First, we need to distinguish between abstraction in art and abstract art. Abstract art is a genre of art that heavily utilizes abstraction. Think of abstraction in art as a scale rather than a binary categorization. The more abstract a piece, the less it resembles the physical world. The more abstract a piece, the less guided the viewer in understanding it. It leaves a lot of space for the viewer to interpret it on their own. And this is a critical component of abstract art.

But that does not mean you have to go all the way. Many paintings and sculptures try to resemble the essence of the real world but skip the parts that do not convey the scene or the emotions that the artist intends.

Computing

Abstraction is one of the most fundamental concepts in computer science, and it can be divided into two broad categories. Abstracting computer concepts and abstracting business concepts. To abstract a computer concept is to hide the details of its inner workings and provide an interface to interact with it. A very common example is predicate abstraction (borrowed from Logic). You want to make, let's say, a sorting algorithm that can sort any arbitrary set of elements. And how can you make such a magical algorithm that does not know the type of its input beforehand? You make the condition on which you compare the elements in the input as part of the input. In other words, if you want to sort a set of integers in ascending order, you pass your integers to this algorithm and give it the sorting operator (the < operator in this case). This way, we abstracted the details of sorting from the details of comparing the values.

On the other hand, business abstraction encompasses almost all of our product work that the end customer interacts with. When building any sort of a product or a feature, you are abstracting something. For example, let's say you're adding a presets feature to an audio mixer. If you press, let's say, the chamber preset, the mixer will have the proper echo, reverb, and gain levels set to simulate a chamber effect. By you adding this feature, you are abstracting the details of configuring the mixer.

How does that tie together?

As we saw, the idea of hiding details and focusing on the essential concept is something that happens all the time around us. It is the foundation of fields like philosophy, art, logic, and computing. Actively looking would show us countless examples in our everyday lives.

Understanding which level of abstraction we are working with and thinking accordingly is a skill one needs to develop and master. Mastering this skill would allow us to become more productive and more innovative.

This post will be my perspective on software design, a compilation of discussions and examples of different principles that we associate with software design.

Keep in mind that this is not meant to be a crash course in software design. If you are interested in such content, I recommend reading System Design by Vasa, Philosophy Of Software Design By John Ousterhout, and The Pragmatic Programmer by David Thomas, Andrew Hunt.

Why do we need software design? Poorly designed systems can lead to catastrophic outcomes for the business. Such as unmaintainable or hard to debug, not extendable, and not scalable systems.

First, let's set a definition of software design. Software design is the process of managing tradeoffs when architecting a system. A system in this definition can be anything from a single process/thread program to a multi-cluster multi-region distributed system.

Simplicity

Simplicity is the most important, easiest to understand, and most challenging to master principle of design. You may have heard of the KISS (keep it simple, stupid) principle. But what does it mean for a system to be "simple".

I define a simple system as a system that can be understood by anyone with minimal domain knowledge. For example, a simple accounting system can be understood by any accountant or any developer with enough accounting background. Keep in mind that simple does not mean feature lacking. On the contrary, simplicity allows for extensibility, as we will discuss in the next section.

As you can infer from the definition, designing a simple system requires understanding the business domain. I previously discussed how understanding the problem helps in driving the solution. Similarly, understanding the business domain helps in shaping your system's design. I would go as far as to say you can infer how much a programmer knows in their domain when reading their code. Vagueness in understanding leads to poorly written code resulting in complexity.

Also, you should avoid any fancy design patterns or tools. If you use a design pattern just because it sounds cool or is commonly used in a certain community, you will introduce unnecessary complexity to the system that could've been avoided. I will share one example inspired by a real-world codebase – this is just one out of many.

class Vehicle:
  	# Moves the vehicle for the specified duration and returns how far it moved in floats.
    def move(self, minutes) -> float:
        ...


class Car(Vehicle):
    def drive(self, mode, seconds) -> float:
        self.move(seconds / 60)
        ...


class Motorcycle(Vehicle):
    ...


def get_distance_travelled(vehicle: Vehicle) -> float:
    distance_travelled = 0
    if isinstance(vehicle, Car):
        distance_travelled = vehicle.drive("sport", 120)
    elif isinstance(vehicle, Motorcycle):
        distance_travelled = vehicle.move(2)
    return distance_travelled

In the previous example, we had a base-type Vehicle that has been extended twice. And it has a method move that takes the duration in minutes and then returns a float of how far this vehicle moved in this duration of time. However, when the new type of Vehicle, Car, was made, the developer found that its concept of moving and its requirements were different than the default move. So, they made a new drive method that took a different combination of parameters.

Given this difference in the interface, the developer had to distinguish between vehicles in the call site and treat them differently, breaking the original premise of inheritance.

Because we do not have enough business context for this example, I won't propose a solution, but this shows how this confused understanding of polymorphism vs. inheritance made this inconsistent design. We would've been better off if we did not make a base class for our vehicles to inherent and relied on duck-typing or interfaces depending on the language.

As you can see, simplicity is hard. It takes a lot of discipline and thought to get anywhere near a simple design.

Scalability

Scalability can be divided into two subcategories extensibility and stability, or functional scalability and load scalability.

By extensibility, I mean the capacity to extend the system by adding new features or altering existing ones. When designing any program, small and large, always think of what features can be added. You do not necessarily have to think in-depth of the implementation details as much as having a vision of how to expand your feature set. Having this in the back of your mind helps you design for expansion.

On the other hand, stability may be the easier of the two. There are so many tutorials on improving the performance and stability of the specific framework or tool you are using. Things like eager loading vs. lazy loading in web apps, caching, JIT compiling, to name a few. However, I summarize all of these tutorials this way: do not do what you do not have to do. Most optimizations revolve around the idea of minimizing resources usage. If you load too much data, you are using too much memory and storage (and maybe network). If you loop too many times, you are using too much compute, and so on.

Keep in mind that the key to scalability is simplicity. If the system is too complex for you to comprehend, it's really hard to know what to optimize.

Design Process

Design is an iterative process. You come up with a cool idea to comply with particular constraints in your requirements, only to realize that it introduces more limitations or does not entirely cover the whole case. You then go back to the drawing board and either refine the proposed solution or start over.

One great way to reduce the time spent trying to implement a solution and later having to redo it is by having design workshops. Having concerned parties of a particular component meet and discuss a solution. Talk about what benefits a solution would provide or the problem it would solve, and most importantly, what constraints it introduces to the system. Also, you can invite people who do not directly deal with the system to have a set of fresh eyes to give a different perspective (this has proven to be very helpful in multiple situations).

Design should not be done in a vacuum. Once you get your first couple of thoughts on paper, try presenting them to others. Trying to explain an idea is the best way to scrutinize it. For example, one time, I had to design a schema for a routing system for shipments. I knew that I needed to know where the shipments are coming from, going to where, on what service type, by whom, and for how much. So, I decided to have each one of these questions solved by a database table.

One table defined origin cities. Another table linked the origin cities to the destination cities for specific service level named destinations. The last table had linked the previous table with couriers and their prices. After sketching this design on paper, I showed it to two fellow engineers on the team. We discussed how this proposed design would be used in code and debated some of the field names. For example:

destination.origin_city vs. destination.origin
destination.cost
...

Given that this destination table was the core piece of our system, we focused on its usage. After a couple of examples, both of the engineers found this confusing. Then we realized that all of this could be reduced to the concept of a route. One table has origin, destination, service_level, and cost fields. And we did not need to debate the naming:

route.origin_city
route.destination_city
route.cost
...

That would not have been achieved without sharing and discussing the design with others, especially potential maintainers of the system.

The first design is probably the worst. So do not get attached to your first idea. Instead, keep challenging it until you verify that it achieves your design goals.

Abstractions

As Butler Lampson says, "All problems in computer science can be solved by another level of indirection." Abstraction (indirection) is a fundamental idea in software design. It helps you define what you are actually trying to solve. Most software products are abstractions of some sort, whether it is an intermediate piece of software used by other software (e.g., APIs) or an end application used by the end-user. We are always trying to abstract something.

So, this makes sense, but how do we tell if a problem should be solved by abstraction? And how do we define the scope of a given abstraction problem?

These two questions can be answered by answering two other questions: how common is this problem? And how wide is the range of use-cases? Let's take, for example, the problem of sending HTTP requests to external web services. How often do we send HTTP requests from our app? If we only have one instance of sending an http request in our app, we should not bother to abstract it. However, if we do have multiple instances, we should look into variance in usage. For example, are these all the same exact request used in various places? Are these requests sent to the same API provider? Are these all the same HTTP method? And so on.

Once we understand the broadness of our use cases, we can start designing our abstraction. Let's say I am building a Twitter client. In this case, I will be interacting heavily with the Twitter API. So, I will make an abstract approach to communicating with it. Look at the following function signature:

def call_twitter(endpoint: str, method: str, params: dict = None) -> dict

The call_twitter takes an endpoint which is the path of the API I want to interact with. I should not include the host information or API version that I have abstracted away from the user. The method is simply the HTTP method that can be passed in lower or upper case. Lastly, the optional params and the return value are dicts given that the Twitter API always takes and returns payload wrapped in an envelope as described here.

In a call site, I would do something like:

tweet = call_twitter("/tweets/2244994945", "GET")

Which would return something like:

{
  "data": {
    "author_id": "2244994945",
    "created_at": "2020-06-24T16:28:14.000Z",
    "id": "1275828087666679809",
    "lang": "en",
    "possibly_sensitive": False,
    "source": "Twitter Web App",
    "text": "Learn how to create a sentiment score for your Tweets with Microsoft Azure, Python, and Twitter Developer Labs recent search functionality.\nhttps://t.co/IKM3zo6ngu"
  }
}

You may also want to explore whether or not to unwrap the response and return thedata field directly as you do not want to end up with tweet["data"]all other the place.

With that being said, some "attempts" at abstractions may yield harmful results. These attempts can be divided into two categories. The first one is immature abstractions. That is when you try to implement an abstraction for the use case that is not well understood. These usually occur in abstractions of business logic. For example, let's say we are trying to implement a tax calculator. The naive way of doing it is to simply make a function that takes the price and multiply it with the rate.

TAX_RATE = 0.15
def calculate_tax(price: Decimal) -> Decimal:
  return price * TAX_RATE

The problem with this design is that it does not account for products with different tax rates and exempted products. If we then needed to support those, we will have to take one of two approaches. The first approach is to handle the exception in the call site, which means the callers need to be smarter. The other approach is to change the function signature to either take the tax rate or the product category and decide the rate internally.

def calculate_tax(price: Decimal, category: str) -> Decimal:
  return price * get_tax_rate(category)

However, this will require that we change all callers to pass this parameter. Note this may seem like a trivial example, but these small things can cause many cascading problems when you're not accounting for this missing value. My rule of thumb here is If you do not understand the domain, do not try to abstract it.

The second category of harmful abstractions is fake abstractions sometimes called empty or pass through abstractions. Look at the following example adapted from real world production codebase:

def update_product_quantities(order, operator):
  for order_product in order.products:
    if operator == "+":
      order_product.product.quantity += order_product.quantity
    elif operator == "-":
      order_product.product.quantity -= order_product.quantity

Then someone came and decided to abstract this function by doing the following:

def deduct_products_quantities(order):
  update_product_quantities(order, "-")
  
def return_products_quantities(order):
  update_product_quantities(order, "+")

As you can see, the two functions only have one line of code each. They do more harm than good, and they are not really abstracting anything. I need to memorize more terminology deduct and return, which are not even proper antonyms. I am assuming that the intention of the developer who made these function to hide the cognitive complexity of the operator parameter. However, they ended up introducing a similar amount of cognitive load when they introduced the new terminology.

Closing Thoughts

Software design is not at all about memorizing common architectures and sprinkling fancy design patterns but instead figuring out what to do and when. Furthermore, it is about doing the least amount of work that would give you the most mileage (remember, simple and scalable).
I may have spent most of this post on abstractions, but I believe that our work as developers is all about abstractions. We apply all the previous principles when we implement abstractions. An abstraction needs to be simple and scalable, which can be achieved by having a good design process.

The motivation for this post: throughout my experience working with many startups, I have rarely seen developers who think holistically about the problems they are supposed to solve. The dilemma we face here is that we sometimes work on products that we are not the immediate users of, so we start making assumptions that may or may not be valid. And sometimes, our users develop habits to work around issues that exist in the product or need entirely new features that are not present in the product in the way we originally intended.

This post will discuss my approach to understanding the customers' needs and feel their pain, and I will give examples from my current work at Zid. Keep in mind that this is my approach, and it may not be as effective for everyone. Also, this is a mindset, not a recipe, meaning it takes time to get it to be part of your intuition, but having the ideas laid out would help you actively think in the following sense.

Note that some of these ideas may sound contradictory, which they are to some extent. You will have to make tradeoffs as needed in your situation.

Be In The Customer's Shoes But Keep The Analytical Hat

As developers, we like to think of things as procedures or a series of logical steps. This mindset is what allows us to write programs out of problem statements. However, your customers are not developers, and they may not know the right questions to ask or how to find the root cause of the pain.

When talking to the customers, you need to forget all your preconceived notions about how the customers use the products or, at the very least, validate them. In other words, do not assume that the user uses the product as you designed it. They might have created new use cases or altered old ones in ways you never thought of.

When you get a feature request, your first intuition should be to ask your customers why they want this feature, and what problem does it solve. Something to keep in mind here is that you should be careful of rephrasing the feature statement instead of discussing the pain. You need to focus on the whys, not the hows, to get a deeper understanding of the issue, instead of suggestions for solutions; failing in that could lead to solving an entirely different problem.

For example, merchants at Zid asked for bulk price updates for their products. After further discussion with the merchants, it turned out that the goal is to make store-wide sales – they wanted to edit the prices beforehand. Here, we asked: what happens when the sale ends? Is it possible to revert the changes? What happens to the product variants? How practical is this suggested approach in achieving the goal?

You Know How To Automate, But The Customer Knows The Business

Now that you understand the problem they are facing. You can start sketching different workflows as your solution candidates. Here, you should be thinking more about which parts of their current process are causing the most headache, how you can eliminate them, what are your current parameters, and what steps are redundant.

One way to tackle these questions is to treat your process as a pipeline of inputs and outputs, where each pipe is a step. You then start removing pipes to see how that affects your flow and the needed inputs to the next step. More often than not, you find that you could either combine steps or remove them altogether because the system already has all needed inputs to execute a particular task – meaning human intervention is redundant in the first place.

Building on our previous sales example, we came up with auto-applied coupons given that we understood the intent behind this feature request. They are coupons that are automatically applied to the cart based on specific rules (e.g., total, shipping address, particular products, etc.). This approach allowed for many more features to be built on top of it, and the requested feature is just one application of this more flexible solution (discount on any cart during the sale).

Do Not Write All The Code At Once, No Matter How Detailed And Thorough The Requirements Were Given – They Will Change

Part of finding the best approach to automating a task is testing it with real customers. Implementing the whole thing all at once and releasing it is the total opposite. Especially if this is a reasonably new business, you will be making a lot of assumptions with very little usage data to back them. I call this premature automation (automation of not well-understood operational procedure). Premature automation could force you to adjust what you already implemented in ways you did not intend, leading to unnecessary refactoring. Keep in mind that you don’t need to refactor the code you didn’t write.

In other words, you should write the minimal amount of code solving the most basic case of the task, then test it with a real user. Once you made sure that your have a sound and solid foundation, you can build the next layer on top of it, and so on.

Give The Knobs To The Business Team

This point may be more specific to internal automation. You want to keep yourself out of the daily operations. Changing a service's price or name should not be only possible by the developer (either through the DB or hardcoded in the codebase). Try to make your parameters easily adjustable by your operations team.

For example, at ZidShip, our team can use our backoffice to alter integrated couriers, from updating pricing models to changing messages to manipulating routing rules for each courier without going through a developer.

However, this may not always be feasible. In some cases, adding these toggles may not be worth the effort put towards it – that is, if changes are infrequent and trivial. But again, do not underestimate the impact of having such options available.

Closing thoughts

This mindset is meant to complement the product manager's role rather than to replace it. A developer's thoughtful input into the product development cycle can significantly enhance the end user's experience. The product manager's role is to be in the company's front line when talking to the customers and getting their feedback, but the developer should still be as keen to learn about the customers. Moreover, the product manager should be mindful of trying to get the full picture to the developer.

Again, do not expect to master this overnight. It will take some time and effort in actively thinking of the right questions to ask to design such well-thought solutions.