Design code and interfaces so that they behave in ways that are intuitive and predictable for users and developers alike. When people interact with your software, they should feel it behaves as expected without needing to double-check or mentally adjust to unexpected quirks. Favoring immutability and more explicit APIs can help reduce surprise for users of functions you write.

Craft

Use the Principle of Least Surprise

Core beliefs behind the approach to coding, relationships, and responsibility.

Strong relationships power great software and will make you more happy personally. When you invest in these connections—with our team, our users, and our community—you create something more meaningful than just software.

Software is built for people, by people

Take the time to connect deeply, whether through heartfelt conversations, collaborative problem-solving, or simply sharing a laugh. Seek out opportunities to meet face-to-face and share insights and experiences. Meetups and conferences are great opportunities like this where possible.

Value in-person connections

People are more willing to work with you if they like working with you. Be thoughtful and express genuine gratitude for the good work of others. Be responsive and accessible to people. Respond to messages in a reasonable amount of time, even if it's just to tell them you've received their message and will get back to them soon (and then of course get back to them soon). Pay people for their work quickly. Be quick to forgive missteps and give the benefit of the doubt. Give credit where it is due and make sure people you work with feel valued for their contributions. If you're not willing to do this with someone, then don't work with them at all.

Be the kind of person people like working with

It's hard to feel good about your work if it doesn't make a positive difference in the lives of those you care about (even if it does pay the bills). Consider the impact of your work on the world around you. It doesn't have to be some huge grand thing that impacts the lives of everyone on the planet but at the very least, put your effort behind things that are a net good in the world. Build software that adds real value without negative trade-offs for users, colleagues, or the world.

Do good in the world

When you weigh the cost of various decisions, factor in your time in the equation. Just because you can 'build it yourself' doesn't mean that's the best use of your time relative to other things you should be doing.

Value your time

As you work on problems, you ask yourself whether a different approach higher up the 'problem tree' could help you and/or your users avoid having to deal with the problem in the first place. There isn't any solution better than not having a problem to begin with. Not only must a problem be compelling enough to solve, but it must also be compelling enough to solve the inevitable problems caused by its solution. You will not optimize the thing that should not exist.

Don't solve problems, eliminate them

Core Philosophy

Development standards, best practices, and decision-making processes.

They are just your current best understanding of how to do something in a given context. As your understanding evolves, so should your practices.

'Best Practices' do not exist

The best way to have no bugs and ship fast is to have no code and ship nothing. Of course you're in the business of delivering value and it's difficult to deliver value with nothing, but you won't stray further into building more than is necessary to avoid building the wrong thing and lock your code (and your mental model) into something that should never have existed in the first place. You want to avoid wasting time by building something that will never be necessary. This is similar to the 'You Ain't Gonna Need It' (YAGNI) and Keep It Simple and Straightforward (KISS) principles.

Do as little as possible

This isn't just a fun saying you've heard before. This makes an actual impact on your ability to deliver the right amount of work to the right problems. Too often you can find yourself stuck in the enjoyment of optimizing the thing that should not exist. Why bother making the wrong thing work or making the thing that doesn't work fast?

Make it work, make it right, make it fast

Prioritize the ability to deliver real value and iterate rapidly while maintaining quality. Fast, reliable iterations enhance the user experience by enabling timely improvements and quick responses to feedback. Sustainable velocity is not just about speed; it's about building processes and codebases that support efficient, low-bug development over the lifetime of the project (however long or short that may be).

Optimize for sustainable velocity

You don't know the future, but you can feel confident things will change and optimize for that. You avoid wastefully spending time on early abstractions and optimizations until you have more context and a clearer picture of what's needed. Prefer options which enable the greatest future flexibility.

Optimize for the unknown

You don't always need the most correct thing. Sometimes you need something that works now. Additionally, each app you build has unique constraints and requirements. You do your best to build the simplest solution that satisfies the requirements while ensuring you do not paint yourself into a corner. Even when it comes to these principles, some level of pragmatism is necessary in their application.

Pragmatism is more important than 'purity'

Consistency in a codebase helps keep things clear and predictable. Using four different patterns or libraries for accomplishing a single task just adds mental overhead. Strive to consolidate these things where it doesn't increase complexity and act with consistency as a team.

Keep it consistent

When evaluating something new, avoid prejudice simply because it's unfamiliar. Evaluate it on its own merits and see if it can earn a place in your mental model and potentially replace something that is more familiar.

Don't confuse simplicity with familiarity

Playing with new things is fun, but when your product code becomes the playground where you learn new things, bad patterns are unwittingly encoded and then naturally propagated over time. Often it's best to make your inexperienced mistakes in less important projects first.

Balance innovation with stability

Users don't know or care what tools and services are used to deliver the promised value. So you take ownership of the entire solution, even if some parts are provided by others (open source, third party services, etc). For this reason, it is important that each dependency you add justifies its value to the solution.

Take ownership

Linters, type checkers, and even formatters are incredibly powerful tools that can help guide our codebases and avoid runtime errors. They replace fine grained low level tests that nobody will write anyway. It can be easy to offload thinking to overly ambitious linting tools. These can cause you to write verbose code or do weird things just to satisfy them. A linting rule must justify its existence. Formatters save enormous amounts of time and arguments about silly things that don't matter. Use one and move on.

Use Static Testing Tools

Occasionally when weighing pros and cons of different approaches to a feature or solution, you'll have issues with each implementation on the pros and cons list. An important factor when evaluating the cons is whether the problems are long term or temporary. Focus on solving long-term problems rather than temporary ones if the solution is intended to last longer than the temporary problems.

Don't prioritize temporary problems over long-term problems

Thinking like a craftsperson

There are many tools and approaches that can solve the same problem. You evaluate each tool on its own merits and in the context of the tradeoffs you have available to you. When you can leverage your existing knowledge and experience, you can move faster.

There is no such thing as the 'right tool for the job'

The ability to transfer skills to different contexts reduces the amount of wasted time and increases velocity. A focus on platform standards will enable greater transferability of skills. This also impacts the ability to bring in others who can join and contribute productively and makes them more likely to do so. There must be a compelling reason to deviate from standards.

Default to standards

When selecting a tool, consider the size, maturity, and activity of its ecosystem. A strong ecosystem contributes to easier hiring, faster onboarding, better support, longevity, and access to reusable components and shared knowledge. Favoring established ecosystems increases the likelihood of long-term maintainability and transferable skills for team members.

Prioritize tools with an ecosystem

Choosing your tools

Going "all in" on a dependency can buy you great velocity, but at the cost of future flexibility. When evaluating dependencies, consider the tradeoffs of adding a dependency vs. the cost of creating and maintaining that functionality yourself.

Avoid tight coupling to dependencies

Build functionality by combining smaller, specialized components instead of creating deep inheritance hierarchies. Composition offers greater flexibility and modularity which will make you move faster as things change over time.

Favor composition over inheritance

Wait until the commonalities scream at you for abstraction so you can be in the right frame of mind to provide that abstraction. Over-abstraction obscures how a system works together.

Avoid Hasty Abstractions (AHA)

Split code by responsibility, so unrelated concerns don’t mix. It’s a form of modularization but applies to both logic and organization. This principle requires a solid understanding of what constitutes a 'concern.' Traditionally, this was confused with 'separation of technologies' where CSS, HTML, and JS were meant to be separated. Rather things which change together should be as close to each other as reasonably possible. This reduces indirection (in some cases it can be completely eliminated) which makes evolving the codebase easier.

Separate concerns

Ensure data and state are managed in one place and consistently accessed from that single source of truth to avoid duplications and inconsistencies. A common mistake is to synchronize state between two different components where instead this should be derived from the state in a centralized place.

Don’t synchronize state, derive it

Architecting your project

Guidelines for testing, performance optimization, and quality assurance.

The more your tests resemble the way your software is used, the more confidence they can give you. Automated tests are by nature more abstract than your users, but using tools that enable you to simulate users as closely as possible will result in more confidence in shipping good experiences and help you avoid test babysitting that results from implementation details-based tests.

Tests should resemble users

When you make an assertion (most often in tests, but also in validation/parsing), make the assertion specific enough that people who see the error understand what the intended behavior is and what about the current state falls short of that intended behavior.

Make assertions specific

Prefer explicit code over implicit configuration and magical abstractions. Boilerplate is not bad by nature (code is read more than it is written), but it's an indicator that a good abstraction could be on the horizon.

Explicit is better than implicit

Most performance optimizations come at a complexity cost. When adding a performance optimization, you do real-world testing to evaluate the before/after to ensure your optimization is worth the effort (and not making things worse).

Weigh the cost-benefit of performance optimizations

Testing & Performance

Principles for debugging, error handling, and building resilient systems.

Give users, processes, and components only the permissions and access they absolutely need. Reduces the risk of unintended behaviors and increases security.

Least privilege

Design systems and processes that catch errors early, ideally at compile or test time rather than at runtime. Implement strict type checks and use automated testing to catch potential issues before code even reaches production. If there's a situation you think should never happen, but the types suggest that it is in fact possible, rather than glazing over the type warnings, add code to handle that case and throw an error with a useful error message indicating that things are in an unusual state.

Design to fail fast and early

Write code that is easy to debug and troubleshoot. This can mean adding meaningful error messages, clear logging, or using tools that make debugging easier. You want to do the setup for these kinds of things now, before production is on fire.

Optimize for the debugging experience

No matter how well you write your code, eventually disaster will strike and you want to have processes and automations in place to make it as easy as possible for recovery. Automatic backups with simple restore automations you can run is an example of how to do this.

Install extinguishers before the fire starts

Debugging & Resilience

Principles for improving the development process and team productivity.

The landscape of developer tools changes on a regular basis. A productive engineer keeps on the lookout for tools that will help them become more productive. Identifying tools and workflow changes that actually make you more productive can be a challenge and weighing the value of the tool against the cost of onboarding is an important skill. It's easy to spend far too much time working on your development environment ("What theme and font is that!?") so avoid spinning your wheels on this. But it's an important skill to continue to stay relevant in the field by adapting to and adopting more productive tools and workflows.

Adapt to and adopt productive tools

Code comments explain the 'why.' Variables/function names explain the 'what.' Code flow explains the 'how.' Documenting public functions and properties (via jsdoc for example) can be extremely helpful.

Document your work

When you can develop offline, it enables you to tighten your feedback loop, iterate faster, and deliver more value. Not because you regularly work without a network connection (though you can), but because it forces you to be more thoughtful about the services upon which you depend and the challenge of setting those things up locally. This also helps your tests be more reliable and issues more reproducible.

Enable Offline development

Your primary branch should be deployable at all times. This requires all validation checks (tests, linting, type checking) to pass before a commit makes it into the main branch. This also typically means when changes are merged, they either bring in a set of commits which can each be deployable on their own or are squashed into a single commit.

Deployable commits

Maintaining a branch with many changes over a long period of time is cumbersome and error prone. Even the best reviewers get tired and confused and will miss important changes in large merge requests.

Small and short lived merge requests

In the process of shipping software, you often get things working and then move on to the next step. When you're ready to increase your velocity, you dive into the abstractions you use to understand how they work so you can use them more effectively.

Go down to level up

Developer Experience

Teamwork, ethics, communication, and career development.

Sharing knowledge with others forces you to ask questions like 'why does this work?' 'is this the best way?' and 'can this be improved?' This deepens your understanding and makes you and those you teach more effective software engineers.

Solidify knowledge through teaching

You can have terrific conversations with coworkers and friends about things you're learning and doing in this industry. Professional conversations can have a much bigger impact depending on their packaging and distribution. Look for ways to increase the reach and impact of the knowledge sharing that naturally occurs when having professional conversations.

Magnify your conversation impact

The very best programmers and teams will fail without effective communication. Opportunities for collaboration are missed and gratitude and kudos are withheld. This has career-wide implications. Your marketing value and communication with the business (also a form of marketing) will focus on the value that's been created for users rather than technical accomplishments. You'll also always give credit where it is due.

Communicate value

There are tons of little ways to make little bits of money. You don't get sucked into this. Introducing money impacts the relationship and people start to feel entitled to more of you and your time. You determine what it is you make your money doing and you make money doing that, and then the rest of your activities you do for free or do not do at all.

Know where to make money

It's easy to get distracted by all of the things you could pack into your product offering or tech stack. So you regularly ask yourself whether the problems you're solving are your unique value proposition or if you should outsource this time and energy. The more time you spend on things outside of your differentiators, the less time you spend on solving the problem for which you're building.

Focus on unique value proposition

You will never know everything. There will be gaps in your knowledge and understanding. It can be easy to immediately reject things which are new and unfamiliar, but do not fall into this trap. The world continues to evolve and while you don't want to be swept away by every fad that comes and goes, you should approach the new with an open and curious mind.

Keep learning

Professional Growth

No success in life can compensate for failure in your most important relationships. Find people you care about and who care about you. Make lasting commitments to them. Keep those commitments. This is where happiness comes from. The perspective you get from these relationships will make you a more effective and efficient person.

Prioritize relationships

'What E'er Thou Art, Act Well Thy Part'

– John Allan

Strive for excellence

Be honest in your dealings with each other and your customers.

Be honest

Strive to understand the reality of relevant context. Your hopes, dreams, and goals are grounded in the current reality and what you can do to push the limits of what is currently possible. You don't complain about reality (beyond what's necessary to understand it), but adjust your position within reality to give you the greatest outcomes.

Embrace reality

Take responsibility for your actions (or inaction), strive to rectify issues, and move forward.

Use the Principle of Least Surprise

Examples