BlogSoftware
Writing maintainable code: conventions that help teams
By Micah Ondiwa, Senior Software Engineer 1 min read
Consistent structure, clear names, small changes and code review make software cheaper to change for years.
Most of a business system's cost comes after launch, in changes and fixes. Code that is easy to read and change keeps that cost down.
Agree conventions
Use a formatter and linter so style is never debated. Agree folder structure, naming and how modules depend on each other.
Name things for the business
Use the words the organisation uses — invoice, admission, consignment — in code, database and screens. It makes conversations with users and reading the code easier.
Keep changes small
Small pull requests are reviewed properly; large ones are approved without being read.
Review every change
A second pair of eyes catches bugs, shares knowledge and keeps standards consistent.
Write down decisions
Short architecture decision records explain why something was built a certain way, which saves future developers from undoing good decisions.
Pay down debt deliberately
Reserve some time in each cycle for improvements, rather than waiting for a rewrite.
See our software engineering services.
About the author
Micah Ondiwa
Senior Software Engineer
Micah Ondiwa writes about software engineering — application architecture, APIs and integration, data and AI-assisted development, and reliable delivery.