About principles.dev and Adam Craven

Adam discovered that he had a knack for software engineering while studying electrical engineering in college. He realized that he had chosen the wrong course and decided to independently pursue his interest in web development. He started coding for fun, but soon transitioned to a paid developer and has since worked for notable companies such as BBC, Nokia, HSBC, and McKinsey.

As he progressed in his career and started working with other people’s code, Adam became curious about other developers’ programming techniques and the logic behind these techniques.

His fascination with the differences in people’s approaches to programming—or “software craftsmanship,” as he calls it—led Adam to start principles.dev, a platform for sharing software engineering principles and the reasoning behind these principles. Principles.dev was recently featured on HackerNews and was ranked in the top stories for a while.

According to Adam, “Principle.dev is a product of years of experience working with software engineering teams and encountering different programming techniques.” He developed a strong desire to improve software craftsmanship and help teams become aligned along his career journey.

Adam started documenting his engineering principles in 2010, when he joined a team more capable than him and had to invent techniques that would enable him to perform at the same level as the rest of the team. Hence, he started making process documents he would rely on to execute similar tasks in the future. As a result, he was able to work on complex projects, which made the team see him as capable.

Because of the success he recorded with his process documents, Adam decided to test his process documents on teams to help them reduce complexities and work together better. However, his processes did not work on the next team he joined, and he was more productive than other team members, having to adopt frameworks for a while instead.

In 2015, Adam joined McKinsey as a consultant, worked with an aligned team, and found the experience amazing. This inspired him to try introducing principles to other programmers again, which resulted in the birth of principles.dev.

In this article, we share details of our conversation with Adam Craven on how teams can apply software engineering principles. But you can also watch the full video of our discussion with Adam below.

What are software engineering principles?

Software engineering principles are beliefs, ideas, laws, and rules that comprise packets of behavior. In Adam’s words, “Principles are basically behavior wrapped around logic that software engineers can use to make themselves more capable.”

Just as you rely on a product manual when using a product for the first time, principles are important when making engineering decisions. But unlike product manuals, principles are normally documented with the reasoning behind them, making them easy for anyone assessing them to understand and apply them to relevant contexts. Also, they can be used over and over again until they become outdated.

Why diverse software engineering teams struggle to work with principles

If you figure out a way to solve a problem for the first time as a software engineer, you might repeat that process until it becomes a habit. Software engineering is habitual, but the problem with habits is that they are detached from the logic behind them. Hence, it’s easy to ignore the reason behind the habits and stick with them.

But principles cannot be treated as habits when communicated to a diverse team. Each team member has their way of approaching projects and cannot be easily swayed. Therefore, you need to show them the reasoning behind the principles you propose to get them on board. As Adam puts it, “Your team needs to be able to interrogate the knowledge behind process documents or principles.”

When principles are not properly articulated, it will be difficult for engineering teams to see the value in them. However, if you communicate the reasoning and importance of principles you share with your team, adopting such principles will be easier, and it will help your team become more aligned.

Why software engineering teams need principles

If you care about making your team more productive, improving software engineering processes, and getting better results from software engineering, then you need to work with engineering principles. But more specifically, your team needs principles for the following reasons:

1. Principles make teams better aligned

According to Adam, “A team that is not aligned is like two people holding a rope and pulling against each other at either end of the rope without getting anywhere, while an aligned team is like two people holding a rope at either end and walking in the same direction. They might go off in a slightly different direction now and again, but always going for the same goal to improve the same thing.”

Aligned teams produce more code and are generally happier teams. But this isn’t always visible, since we can’t read people’s minds. Therefore, teams are less likely to work harmoniously or be aligned if they don’t have common processes guiding their behaviors.

Sharing principles with your teams is a great way to get them aligned and approach tasks similarly. When your team adopts common processes while executing tasks, they’ll be able to work harmoniously.

2. Principles provide access to best practices

With many experienced programmers documenting their processes, engineering teams can access principles coined by professionals who are the best at what they do. They could learn from your finest developers and access years’ worth of knowledge within seconds. This minimizes mistakes and makes project execution a lot easier.

3. Principles are contextually useful

According to Adam, “The value in principles lies in using them at the right time.” Unlike frameworks that require several adaptations to specific projects, principles can be organized according to their value or relevance, making working on projects with them faster.

For instance, you can have top principles on using GraphQL on every CTO’s checklists. If you organize your principles according to their value or relevance, you can simply apply them to relevant tasks.

4. Principles help team members level their skills up faster

One of the reasons why principles are documented is to ensure easy access to relevant principles. When experts in a particular field share the principles they use in such fields, people learning about the field for the first time can learn quickly.

For example, if you’re interested in learning GraphQL, you can look up all the top principles on GraphQL and read them to learn all you need to know to get started. Access to all these relevant principles can help your team build their capability faster.

Why principles are preferable to frameworks

Software development frameworks such as Angular, Django, or React Native facilitate and accelerate software development processes. However, it takes time to understand and master these frameworks, and new frameworks come up frequently.

Senior engineers must have experienced several technology cycles, mastered certain frameworks, and developed principles for using these frameworks. Therefore, it’s easier for them to work with new frameworks. They’ll be able to go beyond these frameworks and apply what they’ve learned to new frameworks. On the other hand, a junior developer may be easily overwhelmed by new frameworks.

If you have a team of senior and junior developers, as is usually the case, this can slow down project execution and cause unalignment. Therefore, it’s advisable to get your team to adopt principles over frameworks. This way, they’ll be less likely to be swayed by new frameworks and can keep on refreshing their capability and extending principles from other frameworks to new frameworks.

In Adam’s words, “Principles allow developers to exist outside of frameworks and use frameworks as tools, rather than integrate with it.” Furthermore, unlike principles, frameworks are not created to solve business problems and can cause unique problems when used incorrectly. Principles are backed by logic, enabling people to deduct their usefulness or lack thereof in any given context.

How to get your team to start applying software engineering principles in their day-to-day activities

Principles make engineering teams aligned, and aligned teams build better software, deliver on organization goals, and work harmoniously. However, it may not be easy to get your team on board with adopting principles.

If you’re facing resistance to principles from your team or wondering how to convince your team to adopt principles in their daily tasks, here are some tips that will help:

1. Look out for alignment during the team-building stage

Adam recommends looking out for alignment during the team-building stage. Asking questions to discover the engineer’s willingness to adopt principles during the hiring process is a good way to determine if they will work harmoniously with the team.

But it’s not about feeding them principles and expecting them to accept said principles with no objections. It would be best to question the logic behind their rejection or acceptance of any principle you suggest to them during code interviews. This way, you’ll be able to help them see the reasoning behind the principles your team adopts or learn new principles from them.

2. Discuss principles during code reviews

Another great way to introduce principles to your team is by talking about principles during code reviews. You can get each developer to share the principles or processes they used in their code. This will help them identify principles that your team can adapt for better results. It also helps your team learn new principles on the go.

3. Document principles as a team

Adam recommends encouraging your team to document principles. When a developer joins your team, they’ll have access to these principles, making them understand what’s going on in your codebase much quicker and ensuring continuity of projects. As Adam puts it, “You’ll be creating an asset for the long-term, rather than something that’s gone when the team disbands.”

4. Be flexible with your team

Your team may not always accept all principles. Some members would have their inputs. Other members might want to doctor the principles or little or adopt a different principle from the one suggested.

Be flexible and open to change and resistance from your team, as long as they understand the logic behind these principles and are aligned. In Adam’s words, “It’s more important to be aligned than to adopt 100% accurate principles.”

How to fix unalignment in your team

If you’re a tech lead and you’re currently experiencing unalignment in your team, breakdown of communication, or different productivity levels from your team members, here are some practical tips you can use to fix this:

1. Share and discuss generally accepted principles with your team

If there’s already unalignment in your team, suggesting or imposing principles will be met with resistance. Therefore, it’s best to initially introduce generally accepted principles to your team until they become comfortable analyzing and adopting them.

Good examples of commonly accepted principles are consistent code conventions that are automatically enforced, such as using JavaScript, JSLint, and Python. Get your team to talk about the reasoning behind these principles. This will introduce them to the concept of using principles in the team.

2. Introduce more principles to your team over time

Once your team becomes comfortable analyzing the reasoning behind principles, you can get them to adopt more principles. At this point, you can create a principle list for the team.

During code reviews, you can criticize codes that don’t align with the principles your team has accepted. This way, they’ll be exposed to more principles and their application.

3. Encourage your team members to question their automatic behaviors

People will be unwilling to let go of automatic behaviors until they are contradicted. Thus, a good way to make your team members more aligned and receptive to principles is by getting them to question their automatic behaviors.

Final thoughts on software engineering principles

Principles improve software craftsmanship by making engineering better for everyone. Getting your team to process and document principles will help your team become aligned and make it easier for new joiners to work on the team’s level.

If you’ve been having second thoughts about adopting principles on your team, now is a great time to start working with them. It may take a while to get your team on board, but with the tips shared in this article, you should be able to articulate the importance of principles to your team and win them over.

Thank you for reading this article. If you’re wondering where to find examples of principles or have some principles that you and your team have found helpful, we recommend heading over to principles.dev to access sample principles or share your own.

Before you go, feel free to check out the following guides and resources on our blog to help you better manage your team and increase your team’s productivity:

Also, if you’re developing a software product or thinking of building one, we have over 17 years of experience helping companies from all over the world with their projects. Feel free to reach out to us at STX Next for support with your software development!