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.

Sometimes you need to go beyond the code and explain overarching patterns and architectural structure and decisions. This is where decision documents and project-level documentation can come in handy.

Keeping this documentation up-to-date over time is challenging, but important for projects which are intended for long-term maintenance and work from a team. Keep the documentation as close to the code as possible to make it easier.

Developer Experience

Document your work

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

Choosing your tools

Craft

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

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

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.

Offline development matters

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.

Having this kind of discipline makes it easier to rollback to any point in time, perform a bisect when trying to identify when a bug was introduced, and understand the evolution of the codebase.

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.

Use of feature flags can help ensure a feature can be merged before being complete while still enabling the commit to be deployable.

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

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.

This will not only expand your own knowledge and exposure, but also help you make and keep friends by not getting defensive whenever something new challenges your current understanding.

As your understanding crystalizes and experience increases with time and exposure, you can update your solutions and even your principles to better reflect your updated context. You avoid stagnation by re-evaluating your principles and practices.

Maintain a growth mindset and don't settle with your current level of ability. Always strive to improve.

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

In practice, this means when you commit to something, you do it and you do it well. Otherwise, don't commit to it in the first place.

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.

Document your work

Examples