It does not really matter if you are experienced or not. If you work at a small company and just started or if you work with a huge legacy product barely capable of moving things forward. Even at The Tech Companies™ you will find the lack of Software Design principles. These are just like what brand means, only about the way we take coding decisions. Decisions that may affect hundreds of millions of people. The how is just as important as the why, and we’ll try to establish some ground on why these are necessary, how your principles directly affect your customers and a few examples to get started writing your own.

Additions and new files in green, deletions and refactors in green. The more frequency the changes are, the more intense the colour. [Source: https://app.scope.ink visualization of github.com/stripe/stripe-android

The idea (reflected above) is to keep the paths as green as possible. Refactors are necessary, but they are also a reflection of technical debt in many cases, and we want to optimize the creation of features and enhancements over the daily noise of style nits, syntax rewrites and framework changes.

The Small Decisions

There are many things in our day to day that distract us from our ultimate objective: allowing the people that are behind the code to focus on functionality and added value to the end users.. The actual use of our time invested into crafting software. If you are reading this article but you are just interested in tech because of itself, for the sake of engineering regardless of cost, this is probably not your post.

Mainly we will see the following themes surrounding the actual thinking and writing of code:

Style: How does the code written look. Does it need semi-colons, or does it not? Does it need space before function parenthesis, or does it not? This section could include variable naming. File and directory structure could be in this section or in semantics, depending on whether you have a Software Design Manifest or not. We’ll go there later.

How does the code written look. Does it need semi-colons, or does it not? Does it need space before function parenthesis, or does it not? This section could include variable naming. File and directory structure could be in this section or in semantics, depending on whether you have a Software Design Manifest or not. We’ll go there later. Syntax: How different pieces of the code should be written. We need an abstract class to implement this bunch of methods, and an interface, and a series of maps and factories and… {set of pompous stuff and tech jargon}. There are aspects of syntax that can be both relevant and difficult to know what’s best; Sometimes there is no perfect solution. Coding is sometimes more art than science and experience plays a huge role. We will try to categorize these aspects later on and lay out some basic philosophy to help you shape your software.

How different pieces of the code should be written. We need an abstract class to implement this bunch of methods, and an interface, and a series of maps and factories and… {set of pompous stuff and tech jargon}. There are aspects of syntax that can be both relevant and difficult to know what’s best; Sometimes there is no perfect solution. Coding is sometimes more art than science and experience plays a huge role. We will try to categorize these aspects later on and lay out some basic philosophy to help you shape your software. Semantics: What each piece of the syntax (statements, variables, function calls) should mean. We will gather in this category every aspect that ties the written code with the reality backing it, the user experience. For example Log In is a semantic term that we easily relate to the greeting between a user and an app where they have been before. Cart is the semantic term that describes the object or the instance or the database entry where a collection of items that is about to be bought or dispatched lies.

What each piece of the syntax (statements, variables, function calls) should mean. We will gather in this category every aspect that ties the written code with the reality backing it, the user experience. For example Log In is a semantic term that we easily relate to the greeting between a user and an app where they have been before. Cart is the semantic term that describes the object or the instance or the database entry where a collection of items that is about to be bought or dispatched lies. Product: How the decisions we take affect the user experience. Tiny decisions that may seem to belong to syntax or semantics may affect the actual user experience. For example: If we have a piece of code that iterates over a list of elements, whether some elements can be null or not, may affect many different parts of the UX: order of the elements, time of response, how other parts of the code should handle it, whether they arise UI bugs or not (more likely they do), …

As you can easily relate, we want to keep discussions short, and focus on creating things rather than have religious wars all over our workplace. So ideally we will restrict work conversations to the product and its design. The remaining aspects are valuable and important, they deserve to be well thought. But they should be thought only once.

As creator of Scope 🔬 the aim of this article will be to promote and measure the productivity of conversations that revolve around product development. This means to enhance and focus on creative work, rather on mechanic, accessory aspects. By reading until the end I hope you have a better idea on what’s a meaningful conversation and what’s just noise.

The Big Decisions

These are the ones that will completely determine the way things are done, regardless of whether we like them or not and whose changes affect drastically our day to day. These relate to the technologies we use (programming languages, environments that are required, tooling) or the targets we have (platforms to distribute, customer range). These decisions should be based on both product and developer experience.

Style, Semantics and Syntax should never condition the ultimate decision, as they may change from context to context, but will be only anecdotal in their nature. As most seasoned developers know language, stack or tooling, this shouldn’t count towards qualifying you as a Great Engineer. For instance, changing technology stacks can be painful at the beginning but it is a very symmetric process always. If you know how to code in Language X, you will know how to code in Language Y. Experience, communication skills, care about people and product and people are qualities that count towards being a Great Engineer however they are seldom measured or taken into account.

There is one big thing that can make a big difference, though. The set of Design Principles that are implicit within each community. Functional-friendly programming languages will bring their own goodies, as other framework-heavy environments will drag your process as you lose the conveniences attached in your comfort zone.

As we get into design principles, and now that you can differentiate between small (daily) and big (one time) decisions, let’s get started with the bigger frame.

The foundations

Just as the Maslow Pyramid, any product company should accomplish the following basics in order:

So Code That Works™ is of the most important. We surely will need the rest if we can focusing on the higher grounds. And this should be the first line of your Design Policy.

Once you are doing something meaningful, your should really improve the way if you want to grow as a company, and for that there are few resources better than Joel Test’s: 12 Steps To Better Code. Really, it never gets old.

We are also going to categorize all the software our organization writes in three blocks:

Business logic: The lines of code that changes the world as we know it. Application Programming Interfaces (APIs!): The lines of code that are made to be solely consumed by other code, business logic or interfaces themselves. Infrastructure: The software we use to run our software. They may have their own business logic, but whose objective is to be the infrastructure for our company code.

After all that you should really take a look into the collaboration process. We talked long and deep over how should we work with one another to reduce bugs, improve productivity, awareness, onboard engineers… If you haven’t done so, you’ll probably like to read How To Measure Creative Work.

A few notes on the infrastructure that you can use, does not matter whether you are big or small: