Blog

• Jonathan Samuel
• Feb 01, 2026
• Code Quality

Notes on Designing for Maintainability as a Student Developer

As students, we are trained to write code that works. We submit assignments, get grades, and move on. Nobody comes back six months later and asks us to add a feature to last semester's project. But in the real world, most of the time you spend with a codebase is not writing it for the first time. It is reading it, debugging it, extending it, and occasionally rewriting parts of it because past you made decisions that present you cannot justify.

Maintainability is the quality of code that makes this ongoing work manageable instead of miserable. It is not glamorous, it does not show up in demos, and it rarely gets praised in code reviews. But it is the single most valuable skill I have developed as a student developer, and I have learned it almost entirely from making mistakes.

What follows are the lessons and practices that have shaped how I think about writing code that lasts, drawn from hands-on experience with real projects.

What Maintainability Actually Means

Maintainable code is not fancy code. It is code that a tired developer at midnight can understand without scrolling back and forth through multiple files trying to piece together what is happening. It is naming variables so they describe their purpose, not their type. It is keeping functions small enough that their purpose is obvious from their name. It is writing comments only when the "why" is not self evident from the code itself.

In the Timetable Generator project, I initially wrote a constraint solver as a single monolithic function spanning over 300 lines. It worked, but every time I needed to add a new constraint like "no professor should teach back to back classes across campus zones" the modification involved reading and understanding all 300 lines to find the right place to insert the logic. Eventually, I refactored it into a pipeline of small, composable constraint checkers. Adding a new constraint became as simple as writing a new function and adding it to the array.

Three Rules I Follow Now

After working across several projects, I have distilled my approach to maintainability into three concrete practices:

1. Separate what changes from what stays the same. Configuration details like API endpoints, database credentials, and feature flags should live in environment variables or configuration files, not scattered across your source code. When I moved the BLE Attendance Tracker from one hardware environment to another, having all hardware specific parameters centralized in a single config file meant the migration took an hour instead of a day.

2. Make dependencies explicit. If a function needs a database connection, pass it as a parameter instead of reaching for a global. If a component relies on a utility function, import it explicitly. Hidden dependencies are the number one reason code breaks when you move it between projects or reorganize your file structure.

3. Write tests for behavior, not implementation. My early tests were brittle because they tested internal implementation details. When I refactored the code, the tests broke even though the behavior was unchanged. Now, I write tests that describe what the system should do from the outside. These survive refactors and actually serve as documentation.

Maintainability Is a Muscle

You do not get good at this by reading about it. You get good at it by revisiting your own code after three months and feeling the pain of poor naming, tangled logic, and missing documentation. That pain is the teacher. If you can, keep working on the same project over a long period. The experience of maintaining your own code through multiple iterations will make you a dramatically better engineer than building ten different throwaway projects. The code you will write next month is always better than the code you wrote last month, and the gap between them is where growth happens.