Engineering teams that value high quality code

We believe the inside of our product needs to look just as great (‘quoting Steve Jobs’).

We strongly believe that having a quality code base is the foundation for fast iteration in a safe environment. Our commitment to quality code is not just lip service either. We have CI tests, follow a style guide, and do all of our code reviews at the design stage. Any non-trivial changes require a design engineering doc to outline and discuss how you’d approach the problem and what tradeoff you may have to make. For those who refer to the Joel Test, we are 12 out of 12 on his list. Of course, we are not 100% perfect and cut corners at times, but we always fully understand the consequences before committing to it.

Traditional wisdom would advise against a full rewrite of our code base, but GoodNotes 5 which we launched in January was actually a full rewrite. We did this because we needed to lay down a new foundation for conflict-free collaboration and cross platform development.

Making things simpler is always our goal – for ourselves and our customers.

We strive for simplicity. When contributing code, Asana engineers always ask the question, “Could this be simpler?” Striving for the simplest, most viable solution requires time and effort up front, but it always pays off in the long-run.

Simple solutions are easier to understand, especially as our codebase grows, and engineers often spend more time reading than writing code. Having code that’s easy to reason about enables them to spot bugs faster and make modifications with confidence.

By reducing complexity, our team is able to create a more reliable, maintainable, and testable application, and therefore a better experience for our users.

We have well defined optimization principles that are part of every engineer's onboarding experience.

They cover code consistency, using data to make decisions, technical leadership, learning from our mistakes, focusing on automation and developer productivity, writing safe, well tested and monitored code, and shipping small changes quickly and continuously.

Additionally, we have an org-wide proportional investment policy that provides the opportunity to prioritize work that helps improve the codebase and developer productivity. While we value urgency and moving quickly, we also favor doing things the right way as opposed to the fast way.

Code should be an enjoyable place to spend most of your day.

As an engineer at HumanFirst, you will spend most of your time writing and interacting with code. Because of this, we spend a lot of time making the code an enjoyable place to be. We understand that a code base is more than the raw bytes that do the work; we place a strong emphasis on documentation, testing, readability, tooling, and extensibility. We have a full set of unit, integration, and end-to-end tests that give us an average of 90% coverage, with some projects reaching 100%. Our APIs have fully interactive documentation (from endpoints to parameters to responses) and our frontend components are documented both in their appearance and behavior using Storybook.

Additionally, we regularly examine pain points and work toward refactoring for better usability. We keep an account of any tech debt we acquire, and make sure to allocate regular time to pay it off. Our ultimate goal is to make sure the structures we have in place help, rather than hinder, both you as an engineer and our ability to serve our customers’ needs.

We actively emphasize style consistency on both the frontend and backend.

As a team, we embrace automation, consistency, and simplicity:

• Automation – We rely heavily on automation to make our code and processes better. We use linting tools for styling automation, CD/CI for deployment automation, and Kubernetes for resiliency and host automation.
• Consistency – We have a documented style guide and component library that advises frontend development. Similarly, we have consistent styles and patterns we align and adopt on the backend. These are constantly iterated on, never stagnant.
• Simplicity – We’re a big believer in KISS and the principle of least astonishment. We treat our code like a product, with engineers being its users. As such, we try to optimize the design to match the user's experience, expectations, and mental models.

Our tech stack is optimized to be modern and easy to pick up, but not excessively flashy. We value new technologies when the benefits are clear, but being pragmatic is our number one priority. Some of the tools we use include:

• React because of its huge developer community and ease of use
• Rails because of its longstanding resiliency and friendly developer experience
• Typescript as a means to embrace type safety and keep sanity in check
• GraphQL because of its friendly developer experience

We take pride in maintaining a high quality code base.

Central to our values of high integrity and a sustainable work culture, we invest in keeping tech debt to a minimum and maintaining a high quality code base from the beginning. Not only does a high quality code base keep our on-call rotation reasonable, but it also limits the time we spend fixing broken or flaky parts. This means we can focus the majority of our time on feature development for our customers. To ensure a high quality codebase we:

• Review all code changes, at a default by two peers.
• Have a mature product lifecycle where larger projects have a scoping, design, user feedback and implementation phase – each of which requires peer feedback.
• Continuously triage and prioritize our feature and bug backlogs.
• Implement a blameless but thorough and educational incident review process.

We don't write throw-away code.

Every day, more and more patients, clinicians, and researchers rely on our data APIs being available, our algorithms processing continuously, and every point in between being 100% secure.

We measure thrice, and cut once. We require an architectural design document for every feature we build, together with a risk matrix to help predict things that can go wrong. We also require code leaving a branch to be production ready, which means it comes with tests and a monitoring strategy. It's more work, and it does mean it takes a little longer until we write that first line of code, but when we do, there are no surprises and it more than makes up for the time spent up-front.

In terms of the staples, our team actively uses and gate merges on peer-reviewed pull requests, lint and static analysis checks, unit tests, and integration tests. We invest heavily in CI/CD automation, 100% of our infrastructure is peer-reviewed code, and we <3 observability!

All this isn't to say that we don't have tech debt. However, our team's approach is to have tech debt that we choose consciously and strategically as we design each feature. Each quarter, we allocate 70% of engineering hours to new feature development and 30% to our internal needs.

All new code has to have tests.

Increasing code quality is a high priority for us. We are given the capacity to do things right, even if it takes longer. Everything is a trade-off: if we can spend a week fixing technical debt now to save us time in the future, then we’ll do it. We’re striving to increase test coverage across our whole codebase.

By using feature flags inside of the product, we can ensure that new customers use the latest and greatest features, while leaving older customers on stable grounds without changing things. Our Customer Success team actively works to migrate customers to the latest version of features so they can be deprecated and removed from the code. Examples: client website migrations, new API explorer, and new markdown parser.

We turn OR operations into AND operations.

First and foremost, having a high quality code base enables us to write new code faster. With a lot of the complexities abstracted, we leverage our code in order to develop more quickly. We utilize controllers in our codebase, which allow us to do operations in Doppler, and each controller has baked in permissioning, security, analytics, bug reporting, and other features so we are secure by default.

While there are many advantages to having quality code, it also isn’t a choice for us. We store incredibly sensitive data for customers, so having high quality code is really a necessity for our business. We’ve gone through two penetration tests, conduct rigorous code reviews, ensure all core flows have end to end tests, and use a dedicated staging environment for QA.

Perhaps this is somewhat unique to Doppler, but we don’t have to compromise between speed and quality. We’re a productivity tool that makes you more secure, and generally speaking, if you’re more secure, you’re more productive. By prioritizing reusability, we’re able to turn OR operations into AND operations.

Quality ∧ (Scope ⊕ Speed)

Article I of our Engineering Constitution is titled: “Never Compromise Quality.” We have a strong bias towards clarity over complexity, simplicity over cleverness when writing code and collaborative, constructive code reviews; from continuous integration to blue/green deploys; and a preference for care over speed when it comes to production. Our platform powers our partners’ day to day operations, and as a result, we strive to build our engineering culture on a bedrock of quality.

Engineers have wide latitude to make sweeping changes across the entire codebase to eliminate lava antipatterns, and we always attempt to fix entire classes of bugs at a time. When mistakes do occur, we practice a no-blame culture and follow the five whys during postmortem.