Skip to main content

Introduction

Introduction to Coding Standards​

Welcome to the coding standards guide. This guide is for you if you write code for PWI.

There’s a lot here, and at first glance it can feel like a lot to take in. We understand that. But we want to reassure you that each article in this guide exists for a reason.

We’ve learned the hard way that when we don’t share a common understanding of what “quality code” means, we introduce unexpected bugs and waste energy solving the same problems again and again. This guide isn’t meant to add friction. It exists because shared standards make our work easier in the long run.

We rarely work alone, and software development is never "done". We work on each other’s code. We come back to our own code weeks or months later. We fix bugs, add features, and extend systems that already exist. All of that depends on being able to understand what the code is doing when we read it again, and be able to make changes without unexpected consequences. Coding standards help capture the patterns, best practices, and decisions that allow us to work well together and understand what we built when we come back to make changes or fix a bug.

This is not a definitive or exhaustive guide to coding standards. It’s a collection of concepts we’ve learned through years of writing code, reading technical books and articles, and making our own mistakes. These are the things we’ve found matter most for working together and for making code easier to understand and change in the future. This guide will change over time as we get better.

How to Use These Standards​

You are ultimately responsible​

These standards are not meant to replace your judgment. They exist to give us a shared baseline and a common understanding of what works and what doesn’t. You don’t need to memorize this guide, but you should read it all. Use it as a reference when writing code, reviewing code, or making decisions about structure and architecture. You may not remember every detail, but you’ll likely remember that a topic is covered here—and you can always come back for a refresher.

These are Values, not Rules​

Almost all of these standards should be considered values rather than rules. Rules must be followed strictly. Values guide us in making decisions, but don't apply the same in every scenario. For example, you may value saving money, but that doesn't mean you never spend money on something frivolous.

There will be times when these standards don't fit the problem you’re solving. That’s expected, especially when it comes to unique architecture. But deviating from these practices should not be done without consideration. When you choose to deviate from a standard, you should have a clear reason for doing so. If you can’t explain why you’re deviating from a standard, that’s usually a sign you shouldn’t be.

Don't rewrite code unless needed​

These standards also aren’t a reason to rewrite working code. When you’re in a codebase, don’t change existing code just to make it match the latest expectations. Doing this could introduce unexpected bugs into the system, especially with poorly-written and fragile codebases. Sometimes the best choice is to leave working code alone unless you’re already modifying it.

Why Coding Standards Matter​

Coding standards exist to make our work easier over time.

When code is inconsistent or unclear, a few things tend to happen:

  • We lose time figuring out how things work
  • We misunderstand what code actually means
  • We duplicate work that already exists
  • We introduce avoidable bugs

Standards help prevent those problems by giving us a shared style of writing code. Standards set expectations around clarity, structure, and quality so that reading and changing code takes less effort.

This isn’t about perfection - nobody writes perfect code. It’s about consistency. When we follow the same principles, reviews get faster, quality improves, onboarding is easier, and we spend less time reading code and more time building useful things.

Code Is Written for People​

One of the main reasons for code standards is that code is actually written for people, not for machines.

The code we write isn’t what a system actually runs. It gets transformed into something the machine understands. But, we don’t usually write in low-level languages like assembly. Low-level languages are precise, but they’re extremely difficult for humans to read and understand, and even harder to write.

We use higher-level languages (closer to common English) because understanding matters. Coding standards support that goal. They help ensure that when someone reads the code - whether it’s a teammate or your future self - they can quickly understand what it does and how to change it safely.

About Examples in This Guide​

You’ll notice that we use specific languages for examples in this guide. When we show an example in a specific language, we generally don’t mean that the idea applies only to that language. We typically choose a language because one or both of the following is true:

  • We are familiar with the language
  • The language provides a concise way to express real-world examples

In any case, you should not need an in-depth understanding of the language shown in order to understand the example.

Most of the principles in this guide are language-agnostic. The examples may be specific, but the principles apply across languages, frameworks, and platforms. In the rare case where a given example applies only to a specific language or framework, we will call that out.