Codebase

Andy Routledge -

A codebase is the complete set of files in a software project – source code, configuration, dependencies, scripts, tests, and documentation. This post explores how this project's codebase is designed and structured.

We discuss the code philosophy, codebase design, developer experience, and the expected code mix and volume. This is the first of a three-part series – Codebase, Code editor, and Code production.

Programming

The process of planning, designing, writing, coding, testing, debugging, and maintaining instructions that tell a computer how to perform tasks. The instructions are written in a programming language such as Javascript or Python.

Coding

The act of writing instructions in a programming language. Coding is a subset of programming.

Programming language

A language used to communicate with a computer and give it step-by-step instructions.

In most languages, code consists mainly of variables, functions, loops, and conditions, which work together by passing and returning data. It often involves importing code, handling errors, responding to events, and working with data.

Markup language

A set of rules and tags used to structure and format text. For example, HTML, Markdown, and SVG.

Styling language

A language that defines the visual presentation of structured content. For example, CSS.

SQL

Structured Query Language (SQL) is a programming language used to manage and manipulate relational databases.

Code

Instructions written in a programming language. 'Code' is typically used as an umbrella term for all languages used to build software – HTML, CSS, Javscript, Python...

Code philosophy

We design the codebase around a small set of core principles:

Code quality

A measure of how "good" and effective the code is across multiple dimensions – usability, reliability, and performance.

Usability

How easy the code is to read, understand, test, modify, and maintain.

Reliability

Code reliability is the ability of code to run correctly and consistently without errors or unexpected failures. It requires error handling, input validation, testing, correct logic, logging, security measures, and other techniques.

Performance

How quickly and efficiently the code executes, including its speed, resource usage, scalability, and responsiveness.

Procedural

We use functional-style programming with procedural orchestration. We prefer function declarations in Javascript and use other function types when appropriate.

Plain

We use core language features directly and avoid unnecessary frameworks, libraries, preprocessors, and abstraction layers.

Testing

We use testing to ensure correctness, enable safe changes, and prevent regressions through automated and manual QA testing.

Minimal dependencies

We avoid unnecessary external dependencies at both runtime and buildtime.

Codebase design

Let's explore how the codebase is designed – folders, files, code organisation, and style guide.

Folders

Simple, consistent structure across languages – account, shared, system, and projects. The top level also includes assets, cache, and tests folders.

assets
  • account
  • shared
  • system
  • projects
cache
  • account
  • shared
  • system
  • projects
cpp
  • account
  • shared
  • system
  • projects
css
  • account
  • animations
  • components
  • elements
  • layouts
  • overrides
  • pages
  • projects
  • settings
  • shared
  • system
html
  • account
  • shared
  • system
  • projects
js
  • account
  • shared
  • system
  • projects
python
  • account
  • shared
  • system
  • projects
rust
  • account
  • shared
  • system
  • projects
sql
  • account
  • shared
  • system
  • projects
tests
  • account
  • shared
  • system
  • projects
  • integration
  • e2e

Files

A simple, consistent file naming system across languages, designed for clarity and easy navigation. Each file has a single purpose, and we split files when necessary to keep them focussed and manageable.

Feature-based naming

All files for a feature share the same base name, eg account.py, account.html, account.css, and account.js.

File types

The following file types are used throughout this project, along with media and other file types when needed:

  • HTML (.html)
  • CSS (.css)
  • Javscript (.js)
  • Python (.py)
  • Rust (.rs)
  • C++ (.cpp)
  • Text (.txt)
  • JSON (.json)
  • SQL (.sql)
  • Bash (.sh)
  • Env vars (.env)
  • TSV (.tsv)

Code organisation

How the code is arranged within files, eg ordering, grouping, comments, and spacing.

Javascript

JS

// File header
/**
    MODULE: account
    PURPOSE: manage user account data and lifecycle
    Copyright © 2026 Your Company
    Created: 10 April 2026
    SPDX-License-Identifier: MIT
*/


// Imports
import { fetch_json } from '../../shared/http/http_fetch.js';
import { add_listener } from '../../shared/events/events.js';
import { add_keyboard_shortcut_listener } from '../../shared/keyboard/keyboard.js';


// Module variables
let refs;
let options;


// Orchestration
function account(element) {
    refs = get_refs(element);
    function_a();
    function_b();
    function_c();
}


// Logic
function function_a() {

}

function function_b() {

}

function function_c() {
    
}


// Refs
function get_refs(element) {
    return {
        // Get node references
    }
}
Example Javascript file structure
1

File header

Defines what the module is and why it exists. Optionally include metadata such as author, copyright, and license information.

2

Imports

Import functionality from other modules into the current file, eg shared modules and submodules.

3

Module variables

Variables declared at the top level of a module, making them accessible to all functions within that module. Example variables include refs, options, state, and debug.

4

Orchestration

Responsible for setup, dependency wiring, and controlling execution flow within the module. The orchestration function is the module's entry point.

5

Logic

The logic layer contains the functions that implement a module's behaviour, including business rules, data tasks (access, persistence, and processing), helper functions, and other operations.

We group functions by responsibility, which can be done manually or automated using code editor functionality. Example function groups:

  • Orchestration
  • Listeners
  • Observers
  • Handlers
  • UI updates
  • Business logic
  • Data access
  • Data processing
  • Data persistence
  • Lifecycle
  • State
  • Helpers
6

Refs

Fetch and store references to HTML elements used throughout the module.

Other programming languages

Python, Rust, and other programming languages follow similar code organisation patterns.

CSS

CSS

/* File header */
/*
    MODULE: account
    PURPOSE: styles for account management UI
*/


/* Imports */
@import url('./account_profile.css');
@import url('./account_settings.css');


/* Blocks */

/* Block */
.ac_card {

}

/* Modifiers */
.ac_card--featured {

}

.ac_card--large {

}

/* States */
/* Container queries */
/* Media queries */

/* Elements */

/* Element */
.ac_card__header {

}

/* Modifiers, states... */

/* Element */
.ac_card__body {

}

/* Modifiers, states... */

/* Element */
.ac_card__footer {

}

/* Modifiers, states... */
Example CSS file structure
1

File header

Defines what the CSS file is and why it exists, and metadata such as author, copyright, and additional information. Optional.

2

Imports

You can import submodule CSS files at the top of a file. Used in development only. CSS files are bundled in production.

Module-based architecture

Each module has its own dedicated set of files, eg account.py, account.js, account.css, and account.html.

3

Blocks

We use a Block-Element-Modifier (BEM) approach to naming. We define all block styles – base, modifiers, states, container queries, media queries – then repeat the same structure for each element inside the block. A CSS file can contain multiple blocks.

A code editor can provide functionality for viewing and navigating styles, eg table of contents, code map, and filters.

CSS style guide

Pixels for media and container queries, folder-based style prefixes, eg sh_ for files in the 'shared' folder, and native variables.

JS style guide

Function declarations by default and minimal nesting – prefer early returns and flat structures. We use similar rules for other programming languages.

Naming conventions

We use snake_case naming for consistency and to reduce cognitive load:

  • CSS selectors and properties
  • Function and variable names
  • Folder names
  • File names

Developer experience (DX)

Refers to the overall experience and satisfaction developers have when working with tools, technologies, and processes, as well as their broader environment – culture, team dynamics, training opportunities, hardware, workspace, work hours, commute, and other factors.

Optimising codebase usability is a key way to enhance DX – lower cognitive load, enhanced flow states, and higher work satisfaction. Good DX also improves staff attraction and retention.

Code mix

These are my estimated lines of code (LOC) percentages per language for this project. 70% frontend, 30% backend:

Comments

For programming languages, 20% of the total code is comments. CSS – 10%. Code-to-comment ratio can vary a lot per file – from 100% code to 50:50 or even more comments than code.

Test code

10% to 15%.

Utility code

5%.

Code volume

~80k lines of code at launch, scaling to millions as the system evolves.