Forem: Rob Johnston

Depend on Abstractions: Testing Without the $50,000 Spectrometer

Rob Johnston — Mon, 02 Feb 2026 14:00:00 +0000

Part 5 of the SOLID Principles for Scientific Programmers series

The Problem Every Scientist Has Faced

You've written a data acquisition script that reads from your laboratory spectrometer—a $50,000 instrument that's booked solid for the next two weeks. Your analysis code works perfectly... when you have access to the hardware.
Then your advisor asks: "Can you run the analysis on last month's data to compare?" You can't—the code only reads from the live spectrometer. "Can you test the new averaging algorithm before the experiment?" You can't—testing requires the actual hardware. "The spectrometer is down for calibration—can you still work on the code?" You can't. Your colleague in another lab wants to use your analysis but has different equipment? Your code is hardwired to your specific sensor.

Your analysis logic is imprisoned by hardware dependencies. Brilliant scientific algorithms rendered useless by tight coupling. Your beautiful working code has become a rigid, untestable monolith.

This is the problem the Dependency Inversion Principle (DIP) solves.

What Is the Dependency Inversion Principle?

The Dependency Inversion Principle states:

High-level modules should not depend on low-level modules. Both should depend on abstractions.

Abstractions should not depend on details. Details should depend on abstractions.

In plain English: Your important scientific logic shouldn't be hardwired to specific hardware, file formats, or external services. Instead, it should depend on interfaces or abstract descriptions of what it needs. The concrete implementations can then be swapped out as needed.

Before You Refactor: Is It Worth It?

DIP adds abstraction layers that take time to design and implement. Before refactoring, consider:

Do you need to test without hardware? This is DIP's killer feature for scientists
Will you swap implementations? (file → database, real sensor → simulated, etc.)
Do multiple people work on the code? DIP enables parallel development
Is the dependency causing pain? (hardware unavailable, slow tests, inflexible code)

If you're blocked because you can't test without the $50K spectrometer connected, DIP refactoring is essential.

A Real Example: The Problem

Let's look at a temperature monitoring system for a materials science experiment. Here's what you may write first:

import serial
import csv
from datetime import datetime

class TemperatureMonitor:
    def __init__(self):
        # Hardcoded dependency on specific hardware
        self.sensor = serial.Serial('/dev/ttyUSB0', baudrate=9600)
        # Hardcoded dependency on specific file format
        self.output_file = 'temperature_data.csv'

    def collect_data(self, duration_seconds):
        """Collect temperature data for specified duration."""
        results = []
        start_time = datetime.now()

        while (datetime.now() - start_time).seconds < duration_seconds:
            # Read from serial sensor
            raw_data = self.sensor.readline()
            temperature = float(raw_data.decode().strip())
            timestamp = datetime.now()

            results.append((timestamp, temperature))

            # Check if temperature is in safe range
            if temperature > 100:
                print(f"WARNING: Temperature {temperature}°C exceeds safe limit!")

        # Save to CSV
        with open(self.output_file, 'w', newline='') as f:
            writer = csv.writer(f)
            writer.writerow(['Timestamp', 'Temperature'])
            writer.writerows(results)

        return results

# Usage
monitor = TemperatureMonitor()
data = monitor.collect_data(3600)  # Collect for 1 hour

Problems with This Design

This code works, but it has serious problems:

Can't test without hardware: You need the physical sensor connected to run any tests
Can't reuse the logic: The safety check and data collection logic is tied to this specific sensor
Can't work with historical data: No way to run the same analysis on previously collected data
Can't switch output formats: What if you want to save to a database instead of CSV?
Can't simulate failures: How do you test what happens when the sensor malfunctions?

The Solution: Dependency Inversion

Let's refactor this using the Dependency Inversion Principle. First, we define abstractions for the things we depend on:

BEFORE (tight coupling):         AFTER (dependency inversion):

┌─────────────────────┐         ┌──────────────────────────────────┐
│ TemperatureMonitor  │         │ TemperatureMonitor               │
│                     │         │                                  │
│ creates:            │         │ depends on:                      │
│  └─> SerialSensor   │         │  └─> TemperatureSensor (abstract)│
│  └─> CSVFile        │         │  └─> DataStorage (abstract)      │
└─────────────────────┘         └──────────────────────────────────┘
         │                                   △
         │ (rigid)                           │ (flexible)
         ▼                          ┌────────┴────────┐
┌─────────────────┐                 │                 │
│ Hardware        │         ┌──────────┐      ┌──────────┐
│ (must exist)    │         │  Serial  │      │   Mock   │
└─────────────────┘         │  Sensor  │      │  Sensor  │
                            └──────────┘      └──────────┘
  ❌ Can't test!                     ✅ Can test anytime!

from abc import ABC, abstractmethod
from datetime import datetime
from typing import List, Tuple

# ABSTRACTION: What we need from a temperature source
class TemperatureSensor(ABC):
    """Abstract interface for any temperature data source."""

    @abstractmethod
    def read_temperature(self) -> float:
        """Read current temperature in Celsius."""
        pass

# ABSTRACTION: What we need from a data storage mechanism
class DataStorage(ABC):
    """Abstract interface for storing temperature measurements."""

    @abstractmethod
    def save(self, data: List[Tuple[datetime, float]]) -> None:
        """Save temperature data."""
        pass

# HIGH-LEVEL MODULE: Now depends only on abstractions
class TemperatureMonitor:
    def __init__(self, sensor: TemperatureSensor, storage: DataStorage):
        # Dependencies are injected, not created internally
        self.sensor = sensor
        self.storage = storage

    def collect_data(self, duration_seconds: int) -> List[Tuple[datetime, float]]:
        """Collect temperature data for specified duration."""
        results = []
        start_time = datetime.now()

        while (datetime.now() - start_time).seconds < duration_seconds:
            temperature = self.sensor.read_temperature()
            timestamp = datetime.now()

            results.append((timestamp, temperature))

            # Business logic is now independent of hardware details
            if temperature > 100:
                print(f"WARNING: Temperature {temperature}°C exceeds safe limit!")

        self.storage.save(results)
        return results

Now we create concrete implementations of our abstractions:

# CONCRETE IMPLEMENTATIONS: Different sensors and different storage

import serial
import csv

class SerialTemperatureSensor(TemperatureSensor):
    def __init__(self, port: str, baudrate: int = 9600):
        self.sensor = serial.Serial(port, baudrate=baudrate)

    def read_temperature(self) -> float:
        raw_data = self.sensor.readline()
        return float(raw_data.decode().strip())

class CSVStorage(DataStorage):
    def __init__(self, filename: str):
        self.filename = filename

    def save(self, data: List[Tuple[datetime, float]]) -> None:
        with open(self.filename, 'w', newline='') as f:
            writer = csv.writer(f)
            writer.writerow(['Timestamp', 'Temperature'])
            writer.writerows(data)

# USAGE: Production - same as before
monitor = TemperatureMonitor(
    sensor=SerialTemperatureSensor('/dev/ttyUSB0'),
    storage=CSVStorage('temperature_data.csv')
)
data = monitor.collect_data(3600)

Why This Is Better: Flexibility Unlocked

Now that we've inverted the dependencies, we can easily create alternative implementations:

1. Test Without Hardware

import random

# MOCK IMPLEMENTATIONS: For testing without hardware
class MockTemperatureSensor(TemperatureSensor):
    """Simulated sensor for testing."""

    def __init__(self, base_temp: float = 25.0, noise: float = 0.5):
        self.base_temp = base_temp
        self.noise = noise

    def read_temperature(self) -> float:
        # Simulate realistic temperature readings
        return self.base_temp + random.uniform(-self.noise, self.noise)

class InMemoryStorage(DataStorage):
    """Store data in memory for testing."""

    def __init__(self):
        self.data = []

    def save(self, data: List[Tuple[datetime, float]]) -> None:
        self.data = data

# Now we can test without any hardware!
test_monitor = TemperatureMonitor(
    sensor=MockTemperatureSensor(base_temp=25.0),
    storage=InMemoryStorage()
)
test_data = test_monitor.collect_data(60)
print(f"Collected {len(test_data)} test measurements")

Benefit: Develop and test anywhere, anytime. No hardware booking required.

2. Test Edge Cases Safely

class FailingTemperatureSensor(TemperatureSensor):
    """Simulate sensor failures for testing error handling."""

    def __init__(self, fail_after: int = 10):
        self.read_count = 0
        self.fail_after = fail_after

    def read_temperature(self) -> float:
        self.read_count += 1
        if self.read_count > self.fail_after:
            raise IOError("Sensor connection lost!")
        return 25.0

# Test failure handling
monitor = TemperatureMonitor(
    sensor=FailingTemperatureSensor(fail_after=5),
    storage=InMemoryStorage()
)
# This will raise an exception - now you can test your error handling!

Benefit: Simulate dangerous conditions (overheating, sensor failures) without risk.

3. Reuse Logic With Different Sources

class HistoricalDataSensor(TemperatureSensor):
    """Replay previously recorded data."""

    def __init__(self, filename: str):
        with open(filename, 'r') as f:
            reader = csv.reader(f)
            next(reader)  # Skip header
            self.temperatures = [float(row[1]) for row in reader]
        self.index = 0

    def read_temperature(self) -> float:
        if self.index >= len(self.temperatures):
            raise IndexError("No more historical data")
        temp = self.temperatures[self.index]
        self.index += 1
        return temp

# Analyze last week's data with the same code!
historical_monitor = TemperatureMonitor(
    sensor=HistoricalDataSensor('last_week_data.csv'),
    storage=InMemoryStorage()
)

Benefit: Same analysis code works with live data, historical data, or simulations.

4. Swap Components Freely

import json
import sqlite3

class JSONStorage(DataStorage):
    """Save data as JSON."""

    def __init__(self, filename: str):
        self.filename = filename

    def save(self, data: List[Tuple[datetime, float]]) -> None:
        json_data = [
            {"timestamp": ts.isoformat(), "temperature": temp}
            for ts, temp in data
        ]
        with open(self.filename, 'w') as f:
            json.dump(json_data, f, indent=2)

class DatabaseStorage(DataStorage):
    """Save data to SQLite database."""

    def __init__(self, db_path: str):
        self.conn = sqlite3.connect(db_path)
        self.conn.execute('''
            CREATE TABLE IF NOT EXISTS temperatures
            (timestamp TEXT, temperature REAL)
        ''')

    def save(self, data: List[Tuple[datetime, float]]) -> None:
        self.conn.executemany(
            'INSERT INTO temperatures VALUES (?, ?)',
            [(ts.isoformat(), temp) for ts, temp in data]
        )
        self.conn.commit()

# Same monitoring code, different storage!
monitor_json = TemperatureMonitor(
    sensor=SerialTemperatureSensor('/dev/ttyUSB0'),
    storage=JSONStorage('temps.json')
)

monitor_db = TemperatureMonitor(
    sensor=SerialTemperatureSensor('/dev/ttyUSB0'),
    storage=DatabaseStorage('temps.db')
)

Benefit: Change storage without touching analysis logic.

The Testing Advantage

The real power of DIP becomes clear when writing tests. Here's a complete example:

import unittest

class TestTemperatureMonitor(unittest.TestCase):
    def setUp(self):
        """Set up test fixtures."""
        self.storage = InMemoryStorage()
        self.sensor = MockTemperatureSensor(base_temp=25.0)
        self.monitor = TemperatureMonitor(self.sensor, self.storage)

    def test_collects_data(self):
        """Test that data collection works."""
        data = self.monitor.collect_data(5)
        self.assertGreater(len(data), 0)
        self.assertEqual(len(self.storage.data), len(data))

    def test_temperature_in_range(self):
        """Test that temperatures are reasonable."""
        data = self.monitor.collect_data(5)
        for timestamp, temp in data:
            self.assertGreater(temp, 20)
            self.assertLess(temp, 30)

    def test_handles_high_temperature(self):
        """Test warning for high temperatures."""
        hot_sensor = MockTemperatureSensor(base_temp=150.0)
        monitor = TemperatureMonitor(hot_sensor, self.storage)

        # Would print warnings, but doesn't crash
        data = monitor.collect_data(5)
        self.assertGreater(len(data), 0)

# Run tests without any hardware connected!
if __name__ == '__main__':
    unittest.main()

No hardware, no external files, no network—just fast, reliable tests.

Real-World Consequences of Tight Coupling

When code depends directly on hardware and external systems:

Graduate student scenario:

Student A writes analysis code tightly coupled to the lab's spectrometer
Student B needs to work on the same code
Only one person can develop at a time—hardware conflict
Testing requires booking lab time and connecting equipment
Bug appears only with certain samples—can't reproduce in testing
Student graduates, code stops working when hardware is upgraded
New student spends months deciphering hardware-dependent code

The problem: The valuable analysis logic is imprisoned by hardware dependencies. Brilliant algorithms become useless when equipment changes.

With DIP: Analysis logic is independent. Test with mock data, develop anywhere, swap hardware freely. The valuable scientific code survives equipment upgrades.

Red Flags That You Need DIP

Watch for these warning signs:

You can't run tests without physical hardware connected
"Just use the production database for development"
Code won't compile/run unless external services are available
You write if testing: ... else: ... branches throughout your code
Team members fight over access to shared hardware
You comment out tests because they require equipment
Changes to hardware require rewriting business logic
You can't work on code while equipment is in use
Switching from file to database requires massive refactoring
Your test suite takes hours because it talks to real systems

If you can't test without expensive equipment, you need DIP.

Common Mistakes: Over-Abstraction

The biggest DIP mistake: abstracting everything.

❌ Don't abstract:

# WRONG: Abstracting basic operations
class Adder(ABC):
    @abstractmethod
    def add(self, a, b): pass

class NumpyAdder(Adder):
    def add(self, a, b):
        return a + b  # Ridiculous!

Just use a + b directly.

✅ Do abstract:

# RIGHT: Abstracting external dependencies
class TemperatureSensor(ABC):
    @abstractmethod
    def read_temperature(self): pass

class SerialSensor(TemperatureSensor):
    def read_temperature(self):
        # Complex hardware communication
        ...

Rule of thumb: Abstract at the boundary where your code meets the outside world (hardware, files, network, databases). Don't abstract internal logic.

Practical Refactoring Strategy

If you have existing code that's tightly coupled, here's how to refactor it:

Step 1: Identify your dependencies (hardware, file I/O, external services)

Step 2: Create abstract interfaces for each dependency

Step 3: Refactor your main class to accept dependencies through its constructor

Step 4: Create concrete implementations of the abstractions

Step 5: Create mock/test implementations

Step 6: Update your code to inject dependencies

You don't have to do this all at once! Start with the dependency that causes you the most pain (usually hardware).

Example: Refactoring tightly-coupled code:

# BEFORE: Tightly coupled
class Analyzer:
    def __init__(self):
        self.sensor = serial.Serial('/dev/ttyUSB0')  # ← Tight coupling

    def analyze(self):
        data = self.sensor.readline()  # ← Can't test without hardware
        return np.mean(data)

# Step 1-3: Extract interface, inject dependency
class Analyzer:
    def __init__(self, sensor: DataSource):  # ← Now flexible
        self.sensor = sensor

    def analyze(self):
        data = self.sensor.read()  # ← Works with any source
        return np.mean(data)

# Step 4-6: Can now test!
mock = MockDataSource()
analyzer = Analyzer(mock)
result = analyzer.analyze()  # ← No hardware needed!

How DIP Relates to Other SOLID Principles

DIP completes the SOLID toolkit:

SRP: TemperatureMonitor has one job (monitoring), not creating sensors
OCP: Add new sensor types without modifying TemperatureMonitor
LSP: All TemperatureSensor implementations are substitutable
ISP: Each abstraction is focused (sensor vs storage, not combined)
DIP: High-level logic depends on abstractions, not concrete hardware

Together, these principles create code that's maintainable, testable, and flexible—exactly what long-running scientific projects need.

Performance Notes

DIP adds a layer of indirection (calling through an interface), but this overhead is negligible compared to actual I/O operations (reading sensors, writing files, database queries).

The real performance benefit: you can optimize or swap implementations without changing calling code. Need a faster storage format? Implement FastBinaryStorage. Need caching? Implement CachedSensor. The abstraction layer enables optimization.

When to Skip DIP

DIP adds upfront complexity. Skip it for:

Quick exploratory scripts (notebook/one-off territory on the spectrum)
One-person projects where you're certain the dependencies won't change
Very simple programs with no testing requirements
Prototypes where you're still figuring out what you need

But consider adding it later when you move from exploratory → production territory:

The code becomes mission-critical
Multiple people need to work on it
You need automated testing
The dependencies start causing pain

Summary

The Dependency Inversion Principle transforms rigid, hardware-dependent scientific code into flexible, testable software. By depending on abstractions instead of concrete implementations, you can:

Test without hardware
Reuse analysis logic with different data sources
Swap components easily
Simulate edge cases
Work on code while equipment is unavailable

The key insight: Your valuable scientific logic should be independent of the messy details of how data gets in and out of your system.

Your Turn

Identify one pain point in your current code where DIP would help
Identify the dependency (sensor, instrument, file format)
Create an abstraction for that dependency
Create a mock implementation for testing
Refactor your code to accept the dependency
Write tests using the mock

Start with just one dependency—the one causing you the most pain.

Series Conclusion

This completes our journey through the five SOLID principles for scientific programming. We've covered:

SRP: Separating concerns so each class has one job
OCP: Extending functionality without modifying tested code
LSP: Ensuring subclasses are truly substitutable
ISP: Creating lean, focused interfaces
DIP: Decoupling logic from hardware dependencies

Together, these principles help you write code that's maintainable, testable, and flexible—code that survives lab equipment changes, team turnover, and evolving requirements.

Remember: Don't apply all principles to all code. Start simple, refactor when pain appears, and use these principles as tools to solve specific problems, not as rigid rules.

Your exploratory Jupyter notebook doesn't need SOLID. Your production pipeline that runs daily for two years? That's where SOLID shines.

Have questions or examples from your own scientific code? Share them in the comments below!

Previous posts in this series:

Lean Interfaces: Why Would a pH Meter Need `set_wavelength()`?

Rob Johnston — Mon, 26 Jan 2026 14:00:00 +0000

Part 4 of the SOLID Principles for Scientific Programmers series

The Interface Bloat Problem

You're writing software to control laboratory instruments in your research group. You create an Instrument interface that defines everything an instrument might need to do: initialize, shutdown, measure, calibrate, read temperature, read pressure, set wavelength, start scanning, and more.

Then someone wants to use your library with a simple thermocouple. Now they have to implement all those methods—10 in total. Several of them throw 'not implemented' errors. Your well-meaning abstraction has become a minefield where every method call might explode at runtime. Your colleague's automated experiment crashes at 2 AM during data collection because the code tried to call get_pressure() on a thermocouple that only measures temperature, and nobody knew this would fail until production.

Later, someone writes code that assumes all Instrument objects support wavelength control. It compiles fine, runs fine with the UV-Vis spectrometer, then crashes with the thermocouple because that feature isn't really implemented.

Your well-intentioned interface has become a burden rather than a help.

This is the problem the Interface Segregation Principle (ISP) solves.

What Is the Interface Segregation Principle?

Robert C. Martin stated it as:

No client should be forced to depend on methods it does not use. ¹

In practical terms for scientists: Break large interfaces into smaller, focused ones. Classes should only implement the interfaces they actually need, not be forced to implement dummy methods for features they don't support.

Think of it like equipment capabilities: Not every instrument needs every feature. Your basic pH meter doesn't need the same interface as your automated high-throughput system. They should implement different interfaces based on their actual capabilities.

Before You Refactor: Is It Worth It?

Interface bloat often appears gradually as requirements accumulate. Before refactoring, consider:

Are implementations writing many raise NotImplementedError? This is the clearest ISP violation signal
Do clients need different subsets of functionality? If every client uses every method, one interface is fine
Is this a public interface? Internal classes used by one client don't need segregation
Are you seeing isinstance checks before method calls? This suggests the interface promises features some implementations don't provide

If implementations are littered with dummy methods or not-implemented errors, ISP refactoring is essential.

A Real Example: The Problem

Let's look at an instrument abstraction that forces everything into one large interface:

from abc import ABC, abstractmethod
import numpy as np
from typing import Any

class Instrument(ABC):
    """
    Master interface for all laboratory instruments.
    Every instrument must implement ALL of these methods!
    """

    @abstractmethod
    def initialize(self) -> None:
        """Initialize the instrument."""
        pass

    @abstractmethod
    def shutdown(self) -> None:
        """Shutdown the instrument."""
        pass

    @abstractmethod
    def measure(self) -> float:
        """Take a measurement."""
        pass

    @abstractmethod
    def calibrate(self, reference: Any) -> None:
        """Calibrate against a reference."""
        pass

    @abstractmethod
    def get_temperature(self) -> float:
        """Read temperature."""
        pass

    @abstractmethod
    def get_pressure(self) -> float:
        """Read pressure."""
        pass

    @abstractmethod
    def set_wavelength(self, wavelength: float) -> None:
        """Set wavelength for optical measurements."""
        pass

    @abstractmethod
    def get_spectrum(self) -> np.ndarray:
        """Acquire full spectrum."""
        pass

    @abstractmethod
    def start_scan(self) -> None:
        """Start a scanning operation."""
        pass

    @abstractmethod
    def stop_scan(self) -> None:
        """Stop scanning."""
        pass

# Simple thermocouple - forced to implement everything!
class Thermocouple(Instrument):
    """Simple temperature sensor."""

    def __init__(self, channel: int):
        self.channel = channel
        self.temperature = 25.0

    def initialize(self) -> None:
        """Actually works."""
        print(f"Thermocouple on channel {self.channel} initialized")

    def shutdown(self) -> None:
        """Actually works."""
        print("Thermocouple shutdown")

    def measure(self) -> float:
        """Returns temperature."""
        return self.get_temperature()

    def calibrate(self, reference: Any) -> None:
        """Thermocouples can be calibrated."""
        print(f"Calibrating against {reference}°C")

    def get_temperature(self) -> float:
        """Actually works - this is what it does!"""
        return self.temperature + np.random.normal(0, 0.1)

    def get_pressure(self) -> float:
        """Thermocouples don't measure pressure!"""
        raise NotImplementedError("Thermocouple doesn't measure pressure")

    def set_wavelength(self, wavelength: float) -> None:
        """Thermocouples aren't optical!"""
        raise NotImplementedError("Thermocouple doesn't use wavelengths")

    def get_spectrum(self) -> np.ndarray:
        """Not a spectrometer!"""
        raise NotImplementedError("Thermocouple can't acquire spectra")

    def start_scan(self) -> None:
        """Not a scanning device!"""
        raise NotImplementedError("Thermocouple doesn't scan")

    def stop_scan(self) -> None:
        """Not a scanning device!"""
        raise NotImplementedError("Thermocouple doesn't scan")

# UV-Vis Spectrometer - also forced to implement everything!
class UVVisSpectrometer(Instrument):
    """UV-Visible spectrometer."""

    def __init__(self):
        self.wavelength = 550.0
        self.initialized = False

    def initialize(self) -> None:
        self.initialized = True

    def shutdown(self) -> None:
        self.initialized = False

    def measure(self) -> float:
        """Returns intensity at current wavelength."""
        return np.random.rand()

    def calibrate(self, reference: Any) -> None:
        """Can calibrate with reference sample."""
        print("Calibrating spectrometer")

    def get_temperature(self) -> float:
        """Spectrometers don't measure temperature!"""
        raise NotImplementedError("UV-Vis doesn't measure temperature")

    def get_pressure(self) -> float:
        """Not a pressure sensor!"""
        raise NotImplementedError("UV-Vis doesn't measure pressure")

    def set_wavelength(self, wavelength: float) -> None:
        """Actually works - this is what it does!"""
        self.wavelength = wavelength

    def get_spectrum(self) -> np.ndarray:
        """Actually works!"""
        wavelengths = np.linspace(200, 800, 100)
        intensities = np.random.rand(100)
        return np.column_stack([wavelengths, intensities])

    def start_scan(self) -> None:
        """Not a scanning instrument!"""
        raise NotImplementedError("UV-Vis doesn't scan")

    def stop_scan(self) -> None:
        raise NotImplementedError("UV-Vis doesn't scan")

# Code that uses instruments has problems
def read_temperature(instrument: Instrument) -> float:
    """Read temperature from any instrument."""
    return instrument.get_temperature()  # Crashes if not a thermometer!

def acquire_spectrum(instrument: Instrument) -> np.ndarray:
    """Acquire spectrum from any instrument."""
    instrument.set_wavelength(550.0)
    return instrument.get_spectrum()  # Crashes if not a spectrometer!

# Usage - runtime errors!
thermocouple = Thermocouple(1)
spectrum = acquire_spectrum(thermocouple)  # CRASH!

uvvis = UVVisSpectrometer()
temp = read_temperature(uvvis)  # CRASH!

Problems with This Design

Problem 1: Forced to Implement Irrelevant Methods

The Thermocouple class has to implement 5 methods it doesn't support, filling them with NotImplementedError or dummy returns.

Problem 2: Runtime Errors Instead of Compile-Time Safety

Code compiles fine even when using unsupported features. Errors only appear at runtime.

Problem 3: Misleading Interface

The interface promises features (e.g., calibration) that many implementations don't actually provide.

Problem 4: Difficult to Understand

Looking at UVVisSpectrometer, which methods actually work? You have to read the implementation to find out.

Problem 5: Fragile Code

Code written against the interface can't rely on anything working. Every method call is a potential runtime error.

The Solution: Interface Segregation Principle

This solves the interface bloat problem: instead of forcing all implementations to support all methods, break interfaces into focused capabilities. Implementations only implement what they actually support.

BEFORE (fat interface):          AFTER (segregated):

┌──────────────┐                ┌────────────┐
│ Instrument   │                │ Instrument │ (base)
│ - initialize │                └────────────┘
│ - measure    │                ┌────────────┐ ┌─────────────┐
│ - calibrate  │                │ Measurable │ │Calibratable │
│ - get_temp   │                └────────────┘ └─────────────┘
│ - get_press  │                ┌──────────────────┐
│ - set_wl     │                │TemperatureSensor │
│ - spectrum   │                └──────────────────┘
│ - scan       │                ┌─────────────┐
│ (10 methods) │                │ Spectrometer│
└──────────────┘                └─────────────┘
       △
       │                        ┌─────────────────┐
  ┌────┴────┐                   │ Thermocouple    │
  │         │                   │ (Instrument +   │
┌──────┐ ┌──────┐               │  TemperatureSensor
│Thermo│ │UVVis │               │  + Calibratable)│
│ 6/10 │ │ 5/10 │               └─────────────────┘
│ NOT  │ │ NOT  │
│ IMPL │ │ IMPL │               ┌──────────────────┐
└──────┘ └──────┘               │ UVVisSpectrometer│
                                │ (Instrument +    │
                                │  Spectrometer +  │
                                │  Measurable +    │
                                │  Calibratable)   │
                                └──────────────────┘

# CORE INTERFACES: Split by actual capabilities

class Instrument(ABC):
    """Base interface - what ALL instruments have."""
    @abstractmethod
    def initialize(self) -> None:
        pass

    @abstractmethod
    def shutdown(self) -> None:
        pass

class Measurable(ABC):
    """Instruments that take measurements."""
    @abstractmethod
    def measure(self) -> float:
        pass

class Calibratable(ABC):
    """Instruments that support calibration."""
    @abstractmethod
    def calibrate(self, reference: Any) -> None:
        pass

class TemperatureSensor(ABC):
    """Instruments that measure temperature."""
    @abstractmethod
    def get_temperature(self) -> float:
        pass

class PressureSensor(ABC):
    """Instruments that measure pressure."""
    @abstractmethod
    def get_pressure(self) -> float:
        pass

class Spectrometer(ABC):
    """Spectroscopy-specific features."""
    @abstractmethod
    def set_wavelength(self, wavelength: float) -> None:
        pass

    @abstractmethod
    def get_spectrum(self) -> np.ndarray:
        pass

class Scanner(ABC):
    """Scanning instruments."""
    @abstractmethod
    def start_scan(self) -> None:
        pass

    @abstractmethod
    def stop_scan(self) -> None:
        pass

# CONCRETE IMPLEMENTATIONS: Only implement what they support!

class Thermocouple(Instrument, TemperatureSensor, Calibratable, Measurable):
    """Simple thermocouple - only temperature capabilities."""

    def __init__(self, channel: int):
        self.channel = channel
        self.temperature = 25.0

    def initialize(self) -> None:
        print(f"Thermocouple on channel {self.channel} initialized")

    def shutdown(self) -> None:
        print("Thermocouple shutdown")

    def measure(self) -> float:
        return self.get_temperature()

    def calibrate(self, reference: Any) -> None:
        print(f"Calibrating against {reference}°C")

    def get_temperature(self) -> float:
        return self.temperature + np.random.normal(0, 0.1)

class UVVisSpectrometer(Instrument, Spectrometer, Measurable, Calibratable):
    """UV-Vis spectrometer - optical capabilities."""

    def __init__(self):
        self.wavelength = 550.0
        self.initialized = False

    def initialize(self) -> None:
        self.initialized = True

    def shutdown(self) -> None:
        self.initialized = False

    def measure(self) -> float:
        return np.random.rand()

    def calibrate(self, reference: Any) -> None:
        print("Calibrating spectrometer")

    def set_wavelength(self, wavelength: float) -> None:
        self.wavelength = wavelength

    def get_spectrum(self) -> np.ndarray:
        wavelengths = np.linspace(200, 800, 100)
        intensities = np.random.rand(100)
        return np.column_stack([wavelengths, intensities])

class ScanningTunnelMicroscope(Instrument, Scanner, Measurable):
    """STM - scanning and measuring, but not optical."""

    def initialize(self) -> None:
        print("STM initialized")

    def shutdown(self) -> None:
        print("STM shutdown")

    def measure(self) -> float:
        return np.random.rand()

    def start_scan(self) -> None:
        print("Starting scan")

    def stop_scan(self) -> None:
        print("Stopping scan")

# Now functions specify exactly what they need!

def read_temperature(sensor: TemperatureSensor) -> float:
    """Read temperature from any temperature sensor."""
    return sensor.get_temperature()

def acquire_spectrum(spec: Spectrometer) -> np.ndarray:
    """Acquire spectrum from any spectrometer."""
    spec.set_wavelength(550.0)
    return spec.get_spectrum()

def calibrate_if_possible(instrument: Instrument, reference: Any) -> None:
    """Calibrate instrument if it supports calibration."""
    if isinstance(instrument, Calibratable):
        instrument.calibrate(reference)
        print("Calibrated")
    else:
        print("Instrument doesn't support calibration")

# USAGE: Type-safe and clear!
thermocouple = Thermocouple(1)
temp = read_temperature(thermocouple)  # ✓ Works

uvvis = UVVisSpectrometer()
spectrum = acquire_spectrum(uvvis)  # ✓ Works

# Graceful handling of optional features
calibrate_if_possible(thermocouple, 25.0)  # Calibrate with temperature reference
calibrate_if_possible(uvvis, reference_spectrum)  # Calibrate with spectrum reference

stm = ScanningTunnelMicroscope()
calibrate_if_possible(stm, None)  # Prints "doesn't support calibration"

# Type checker prevents errors!
# spectrum = acquire_spectrum(thermocouple)  # ✗ Type error - not a Spectrometer
# temp = read_temperature(uvvis)  # ✗ Type error - not a TemperatureSensor

Why This Is Better

1. Implement Only What You Support

Thermocouple implements only the 5 methods it actually supports instead of all 10 interface methods. No dummy implementations for the 5 it doesn't support!

2. Type Safety

Functions declare exactly what they need:

def read_temperature(sensor: TemperatureSensor)

Type checkers verify you're passing compatible sources at compile time.

3. Clear Capabilities

Looking at class declaration tells you exactly what it supports:

class UVVisSpectrometer(Instrument, Spectrometer, Measurable, Calibratable)

4. Flexible Combinations

Different sources implement different combinations of interfaces based on their actual capabilities.

5. Graceful Feature Detection

if isinstance(instrument, Calibratable):
    instrument.calibrate(reference_sample)

Code can check for optional features without causing errors.

Python-Specific: Protocols vs ABCs

Python 3.8+ added Protocols for structural typing (duck typing with type hints):

from typing import Protocol

class TemperatureSensor(Protocol):
    """Temperature sensor as a Protocol - no inheritance needed!"""

    def get_temperature(self) -> float:
        """Read temperature."""
        ...

# Any class with a get_temperature() method is automatically a TemperatureSensor!
class MyCustomThermometer:
    def get_temperature(self) -> float:
        return 25.0 + np.random.normal(0, 0.1)

def monitor(sensor: TemperatureSensor):
    """Works with anything that has get_temperature()."""
    return sensor.get_temperature()

# No inheritance needed!
custom = MyCustomThermometer()
monitor(custom)  # Type checker is happy

Use Protocols when:

You want duck typing with type checking
Third-party classes can't inherit from your interfaces
You want minimal coupling

Use ABCs when:

You want to enforce implementation
You want to provide shared method implementations
You want explicit interface contracts

Role Interfaces vs Interface Segregation

Question: "If ISP says split interfaces, why would I ever combine them?"

Answer: Role interfaces compose smaller interfaces when multiple capabilities are genuinely always needed together for a specific role:

# ROLE: Environmental monitoring station
class EnvironmentalMonitor(TemperatureSensor, PressureSensor):
    """Must monitor both temperature and pressure."""
    pass

# ROLE: Analytical instrument
class AnalyticalInstrument(Measurable, Calibratable):
    """Research-grade instruments need measurement and calibration."""
    pass

# Specific implementation combines roles
class WeatherStation(EnvironmentalMonitor, AnalyticalInstrument):
    """Weather station is both an environmental monitor and an analytical instrument."""
    pass

This is fine! Role interfaces compose smaller interfaces. The key: don't force implementation of methods that aren't needed.

Testing with Segregated Interfaces

With fat interface, would need to mock everything:

class TestWithFatInterface(unittest.TestCase):
    def test_get_temperature_old_way(self):
        mock_instrument = Mock(spec=Instrument)
        # Must mock 10 methods even though we only use read()!
        mock_instrument.get_temperature.return_value = 25
        mock_instrument.get_pressure = Mock()
        mock_instrument.set_wavelength = Mock()
        mock_instrument.get_spectrum = Mock()
        # ... more mocks we don't even use!

        result = read_temperature(mock_instrument)

Small interfaces make testing easier:

import unittest
from unittest.mock import Mock

class TestInstrumentReading(unittest.TestCase):
    def test_measure_temperature(self):
        """Test with minimal mock - only need get_temperature() method."""
        mock_sensor = Mock(spec=TemperatureSensor)
        mock_sensor.get_temperature.return_value = 25.0

        result = read_temperature(mock_sensor)

        self.assertEqual(result, 25.0)
        mock_sensor.get_temperature.assert_called_once()

Real-World Consequences of Interface Bloat

When interfaces force dummy implementations, you create false promises:

Data processing pipeline:

Interface promises all instruments support scanning
Both the Thermocouple and UVVisSpectrometer implementations throw NotImplementedError
Pipeline code calls start_scan() on all sources
Works fine during testing (test data happens to be scannable)
Crashes in production when using a thermocouple
Hours of debugging to find the "not implemented" error

The problem: The interface lied. It claimed all data sources could be scanned, but they can't. The type system gave false security.

Better approach: Segregate interfaces so clients depend only on what they actually need. Scannability becomes an optional feature you check for, not a mandatory method you hope works.

Red Flags That You Need ISP

Watch for these warning signs:

Multiple raise NotImplementedError in a class
Many empty method implementations that just pass
Methods that return None or empty values as placeholders
Documentation that says "not all implementations support this"
isinstance() checks before calling interface methods
Implementations that only use 20-30% of interface methods
Comments like "TODO: implement this" that never get done
Clients that only ever call 2-3 methods from a 10-method interface
Different implementations consistently leave different methods unimplemented

If you're writing more NotImplementedError than actual implementation, your interface needs segregation.

Common Mistakes

Mistake 1: Too Many Small Interfaces

Don't create an interface for every single method:

# TOO GRANULAR
class CanGetX(ABC):
    @abstractmethod
    def get_x(self): pass

class CanGetY(ABC):
    @abstractmethod
    def get_y(self): pass

# BETTER: Group related operations
class Point2D(ABC):
    @abstractmethod
    def get_x(self): pass

    @abstractmethod
    def get_y(self): pass

Mistake 2: Interfaces That Are Still Too Large

# STILL TOO LARGE
class DataProcessing(ABC):
    @abstractmethod
    def load(self): pass

    @abstractmethod
    def clean(self): pass

    @abstractmethod
    def transform(self): pass

    @abstractmethod
    def analyze(self): pass

    @abstractmethod
    def visualize(self): pass

# BETTER: Split by client needs
class DataLoader(ABC):
    @abstractmethod
    def load(self): pass

class DataCleaner(ABC):
    @abstractmethod
    def clean(self, data): pass

class DataAnalyzer(ABC):
    @abstractmethod
    def analyze(self, data): pass

Mistake 3: Splitting Based on Implementation, Not Clients

# WRONG: Split by what implementations have
class FileSystemSource(ABC):
    """Everything file-based sources might do."""
    pass

class NetworkSource(ABC):
    """Everything network sources might do."""
    pass

# RIGHT: Split by what clients need
class Readable(ABC):
    """Clients that read data."""
    pass

class Cacheable(ABC):
    """Clients that need caching."""
    pass

ISP is about client needs, not implementation details.

When to Segregate Interfaces

Segregate when:

Different clients need different subsets of functionality
Implementations often don't support all features
You find yourself writing many raise NotImplementedError
You have optional features that not all implementations provide

Don't segregate when:

All implementations genuinely need all methods
The methods are tightly coupled (can't use one without the others)
You're creating an internal class, not a public interface
Segregation would create more confusion than clarity

The Client Perspective

ISP is about clients (code that uses interfaces), not implementations:

# This function only needs temperature capability
def monitor_temperature(sensor: TemperatureSensor):
    temp = sensor.get_temperature()
    return temp

# Works with ANY temperature sensor!
monitor_temperature(thermocouple)
monitor_temperature(weather_station)
monitor_temperature(temp_probe)

# Doesn't care about pressure, wavelength, scanning, etc.

Performance Notes

Segregated interfaces don't add performance overhead. The cost of implementing multiple small interfaces is zero at runtime—it's just a compile-time organization tool.

The real performance benefit: clients can depend on minimal interfaces, loading only necessary dependencies. A function needing only TemperatureSensor doesn't load spectrometer libraries, scanning hardware drivers, or pressure calibration modules.

Summary

The Interface Segregation Principle says: No client should be forced to depend on methods it does not use.

Following ISP in scientific code:

Reduces dummy implementations
Improves type safety
Makes capabilities explicit
Enables flexible combinations
Simplifies testing
Creates more maintainable code

The key insight: Design interfaces from the client's perspective, not the implementer's. Ask "What does this client need?" not "What can this implementation do?"

Think of it like lab equipment: A pH meter doesn't need a "set wavelength" method just because it's an instrument. Design interfaces for what clients need, not for every possible instrument feature.

Practical Guidelines

Before creating an interface, ask:

Will all implementations support all methods?
Do all clients need all methods?
Are there natural groupings of methods?
Can I split this into smaller, focused interfaces?

If you find yourself:

Writing raise NotImplementedError frequently
Implementing dummy methods
Checking isinstance before calling methods
→ Your interface needs segregation

Your Turn

Find a large interface in your code
List which implementations support which methods
Group methods by which clients use them together
Split into smaller interfaces
Update implementations to only implement what they support

In the final post of this series, we'll bring together all five SOLID principles and discuss when to apply them (and when not to) in real scientific programming scenarios.

Have you written raise NotImplementedError more times than you'd like? Share your interface horror stories in the comments!

Previous posts in this series:

Next in this series:

The Dependency Inversion Principle for Scientists - Coming next week

Martin, Robert C., Agile Software Development: Principles, Patterns, and Practices (paid link). Pearson Education, 2003. ↩

When Your Cheap Sensor Breaks Everything: Understanding LSP

Rob Johnston — Mon, 19 Jan 2026 14:00:00 +0000

Part 3 of the SOLID Principles for Scientific Programmers series

The Sensor Swap Disaster

You've built a data acquisition system that works perfectly with your lab's standard temperature sensor. The code collects data, applies calibration corrections, and flags readings outside the valid range. Everything is tested and working.

Then you need to swap in a different sensor model—maybe the original is broken, or you're using equipment at a collaborator's lab. The new sensor is also a temperature sensor, so you create a CheapTemperatureSensor subclass. The code runs without errors.

But then you notice something wrong: your analysis is giving bizarre results. After hours of debugging, you discover the cheap sensor returns values in Fahrenheit instead of Celsius. Your results are off by a factor of ~2, and other colleagues have based their experiments on your flawed data.

You used inheritance, but you broke a critical principle: substitutability.

This is what the Liskov Substitution Principle (LSP) prevents.

What Is the Liskov Substitution Principle?

Barbara Liskov stated it formally as:

If S is a subtype of T, then objects of type T may be replaced with objects of type S without altering any of the desirable properties of the program.

In simpler terms for scientists: If you inherit from a class, the child class should be a drop-in replacement for the parent. Code using the parent class should work correctly with any child class without knowing the difference.

Think of it like equipment standards in a lab: If your experiment needs a pressure sensor with ±1% accuracy reporting in kPa, any sensor meeting that spec should work. You shouldn't need to rewrite your experiment for each sensor brand—as long as they honour the spec. If a sensor reports in PSI instead, or only works in a narrower range, it violates the "standard"—and your experiment breaks.

Before You Refactor: Is It Worth It?

LSP violations often hide until you try to substitute classes. Before refactoring, consider:

Do you have multiple implementations of the same concept? (multiple sensors, readers, algorithms)
Does code break when you swap implementations? This is the clearest LSP violation signal
Are you using inheritance? If no inheritance, LSP doesn't apply
Do different implementations have different behavior contracts? (units, ranges, capabilities)

If you have multiple implementations that should be interchangeable but aren't, LSP refactoring is essential.

A Real Example: The Problem

Let's look at a sensor abstraction that seems reasonable but violates LSP:

import numpy as np
from datetime import datetime
from dataclasses import dataclass
from typing import Optional

@dataclass
class Measurement:
    """A measurement with value and uncertainty."""
    value: float
    uncertainty: float
    units: str
    timestamp: datetime

class TemperatureSensor:
    """Base class for temperature sensors."""

    def __init__(self, sensor_id: str):
        self.sensor_id = sensor_id
        self.calibration_offset = 0.0

    def read(self) -> Measurement:
        """Read temperature in Celsius with uncertainty."""
        # Placeholder - subclasses will implement
        raise NotImplementedError

    def calibrate(self, reference_temp: float, measured_temp: float):
        """Calibrate sensor against known reference."""
        self.calibration_offset = reference_temp - measured_temp
        print(f"Sensor {self.sensor_id} calibrated: offset = {self.calibration_offset:.2f}°C")

    def is_reading_valid(self, measurement: Measurement) -> bool:
        """Check if reading is within valid sensor range."""
        # Most lab sensors work in range -50 to 200°C
        return -50 <= measurement.value <= 200

class PrecisionTemperatureSensor(TemperatureSensor):
    """High-precision lab sensor."""

    def read(self) -> Measurement:
        # Simulate reading from hardware
        raw_value = 25.0 + np.random.normal(0, 0.1)
        corrected_value = raw_value + self.calibration_offset

        return Measurement(
            value=corrected_value,
            uncertainty=0.1,
            units="Celsius",
            timestamp=datetime.now()
        )

class CheapTemperatureSensor(TemperatureSensor):
    """Low-cost sensor with limitations."""

    def read(self) -> Measurement:
        # Simulate reading from cheap hardware
        raw_value = 77.0 + np.random.normal(0, 2.0)  # Returns Fahrenheit!

        # Doesn't apply calibration offset (hardware limitation)
        # Doesn't provide uncertainty (not capable)

        return Measurement(
            value=raw_value,  # Wrong units!
            uncertainty=0.0,   # No uncertainty info!
            units="Fahrenheit",  # Different units!
            timestamp=datetime.now()
        )

    def calibrate(self, reference_temp: float, measured_temp: float):
        """This sensor can't be calibrated."""
        print(f"Warning: {self.sensor_id} does not support calibration")
        # Doesn't set calibration_offset!

class FastTemperatureSensor(TemperatureSensor):
    """High-speed sensor with reduced range."""

    def read(self) -> Measurement:
        raw_value = 25.0 + np.random.normal(0, 0.5)
        corrected_value = raw_value + self.calibration_offset

        return Measurement(
            value=corrected_value,
            uncertainty=0.5,
            units="Celsius",
            timestamp=datetime.now()
        )

    def is_reading_valid(self, measurement: Measurement) -> bool:
        """Fast sensor only works in narrow range."""
        return 0 <= measurement.value <= 100  # Narrower range!

# Code that uses sensors
class ExperimentRunner:
    """Runs an experiment with temperature monitoring."""

    def __init__(self, sensor: TemperatureSensor):
        self.sensor = sensor
        self.data = []

    def run_experiment(self, duration_seconds: int):
        """Collect data for specified duration."""
        print(f"Starting experiment with {self.sensor.sensor_id}")

        for i in range(duration_seconds):
            measurement = self.sensor.read()

            # Assume all measurements are in Celsius!
            if not self.sensor.is_reading_valid(measurement):
                print(f"WARNING: Invalid reading: {measurement.value}°C")
                continue

            # Assume uncertainty is always provided
            if measurement.uncertainty > 1.0:
                print(f"WARNING: High uncertainty: {measurement.uncertainty}°C")

            self.data.append(measurement)

        self._analyze_results()

    def _analyze_results(self):
        """Analyze collected data."""
        values = [m.value for m in self.data]
        uncertainties = [m.uncertainty for m in self.data]

        mean_temp = np.mean(values)
        mean_uncertainty = np.mean(uncertainties)

        print(f"\nResults:")
        print(f"  Mean temperature: {mean_temp:.2f}°C")
        print(f"  Mean uncertainty: {mean_uncertainty:.2f}°C")
        print(f"  Samples collected: {len(self.data)}")

# Usage - looks fine at first!
print("=== Precision Sensor ===")
precise_sensor = PrecisionTemperatureSensor("TEMP-001")
precise_sensor.calibrate(25.0, 25.5)
experiment1 = ExperimentRunner(precise_sensor)
experiment1.run_experiment(10)

print("\n=== Cheap Sensor ===")
cheap_sensor = CheapTemperatureSensor("CHEAP-001")
cheap_sensor.calibrate(25.0, 77.0)  # Thinks it's calibrating!
experiment2 = ExperimentRunner(cheap_sensor)
experiment2.run_experiment(10)  # Results will be nonsense!

print("\n=== Fast Sensor at High Temp ===")
fast_sensor = FastTemperatureSensor("FAST-001")
experiment3 = ExperimentRunner(fast_sensor)
# If temp goes above 100°C, validation fails unexpectedly!

Problems with This Design

This code violates LSP in multiple ways:

Violation 1: Changed Units

CheapTemperatureSensor.read() returns Fahrenheit, but the base class contract expects Celsius. The ExperimentRunner has no idea and treats all values as Celsius, producing nonsense results.

Violation 2: Broken Calibration

CheapTemperatureSensor.calibrate() doesn't actually calibrate. Code calling calibrate() expects it to work, but it silently fails.

Violation 3: Missing Uncertainty

CheapTemperatureSensor returns uncertainty=0.0. Code checking if uncertainty > 1.0 never triggers, missing important warnings.

Violation 4: Stricter Validation

FastTemperatureSensor.is_reading_valid() has a narrower range than the base class promises. Valid readings for TemperatureSensor (150°C) are invalid for FastTemperatureSensor.

The core problem: You can't safely substitute these subclasses for the base class. Each one breaks expectations in different ways.

The Solution: Liskov Substitution Principle

Let's redesign this following LSP. The key: Make sure all subclasses honour the base class contract.

BEFORE (violates LSP):          AFTER (follows LSP):
┌──────────────────┐            ┌──────────────────┐
│ TemperatureSensor│            │ TemperatureSensor│
│ read() → °C      │            │ read() → °C      │
│ calibrate()      │            │ (contract)       │
└──────────────────┘            └──────────────────┘
         △                                △
         │                                 │
    ┌────┴────┐                       ┌────┴────┐
    │         │                       │         │
┌───────┐ ┌────────┐            ┌────────┐ ┌────────┐
│Cheap  │ │Fast    │            │Economy │ │Fast    │
│→ °F ❌│ │0-100❌│            │→ °C ✅ │ │0-100✅│
│no cal❌│ │      │            │cal ✅   │ │       │
└───────┘ └────────┘            └────────┘ └────────┘
   Breaks contract              Honours contract

import numpy as np
from datetime import datetime
from dataclasses import dataclass
from typing import Optional
from abc import ABC, abstractmethod

# DATA STRUCTURE: Measurement with validation
@dataclass
class Measurement:
    """A measurement with value and uncertainty in standard units."""
    value: float  # Always in Celsius for temperature
    uncertainty: float  # Always positive, in same units as value
    timestamp: datetime

    # Enforces invariant: uncertainty must be non-negative
    # This prevents subclasses from violating the contract
    def __post_init__(self):
        """Validate measurement invariants."""
        if self.uncertainty < 0:
            raise ValueError("Uncertainty cannot be negative")

# BASE CLASS: Defines the contract all sensors must follow
class TemperatureSensor(ABC):
    """
    Base class for temperature sensors.

    CONTRACT:
    - read() returns temperature in Celsius with uncertainty
    - Uncertainty is always >= 0
    - Valid temperature range: -50 to 200°C (expandable via properties)
    - calibrate() adjusts future readings by the given offset
    - All subclasses must honour these guarantees
    """

    def __init__(self, sensor_id: str, valid_range: tuple = (-50, 200)):
        self.sensor_id = sensor_id
        self.calibration_offset = 0.0
        self.min_temp, self.max_temp = valid_range

    @abstractmethod
    def _read_raw(self) -> tuple[float, float]:
        """
        Read raw value and uncertainty from hardware.

        Returns:
            (value_celsius, uncertainty_celsius): Both in Celsius

        Must be implemented by subclasses to handle their specific hardware.

        WHY THIS DESIGN:
        By keeping read() in the base class and making _read_raw() abstract,
        we guarantee that calibration is always applied consistently. If we
        made read() abstract, subclasses might forget to apply calibration_offset,
        violating the contract. This pattern enforces the contract automatically.

        Note: Python doesn't have 'final' keywords to prevent overriding read(),
        so this is a convention. Trust your team to follow it.
        """
        pass

    def read(self) -> Measurement:
        """
        Read temperature in Celsius with uncertainty.

        This method is FINAL - subclasses should not override it.
        Instead, implement _read_raw().
        """
        raw_value, uncertainty = self._read_raw()
        corrected_value = raw_value + self.calibration_offset

        return Measurement(
            value=corrected_value,
            uncertainty=uncertainty,
            timestamp=datetime.now()
        )

    def calibrate(self, reference_temp: float, measured_temp: float):
        """
        Calibrate sensor against known reference.

        All future readings will be adjusted by the calculated offset.
        Subclasses should not override this unless they have special
        calibration procedures.
        """
        self.calibration_offset = reference_temp - measured_temp
        print(f"Sensor {self.sensor_id} calibrated: offset = {self.calibration_offset:.2f}°C")

    def is_reading_valid(self, measurement: Measurement) -> bool:
        """
        Check if reading is within this sensor's valid range.

        Subclasses can have narrower ranges but not wider.
        """
        return self.min_temp <= measurement.value <= self.max_temp

    def get_valid_range(self) -> tuple[float, float]:
        """Return the valid temperature range for this sensor."""
        return (self.min_temp, self.max_temp)

# CONCRETE IMPLEMENTATIONS: Each honors the contract

class PrecisionTemperatureSensor(TemperatureSensor):
    """
    High-precision lab sensor.

    - Uncertainty: ±0.1°C
    - Range: -50 to 200°C
    - Supports calibration
    """

    def _read_raw(self) -> tuple[float, float]:
        """Read from precision hardware."""
        # Simulate high-precision hardware (returns Celsius)
        value = 25.0 + np.random.normal(0, 0.1)
        uncertainty = 0.1
        return value, uncertainty

class EconomyTemperatureSensor(TemperatureSensor):
    """
    Low-cost sensor that properly handles its limitations.

    - Higher uncertainty: ±2.0°C
    - Range: -50 to 200°C
    - Hardware returns Fahrenheit but we convert it
    - Supports calibration
    """

    def _read_raw(self) -> tuple[float, float]:
        """Read from economy hardware and convert to Celsius."""
        # Hardware returns Fahrenheit
        value_f = 77.0 + np.random.normal(0, 2.0)

        # Convert to Celsius to honour the contract
        value_c = (value_f - 32) * 5/9

        # Higher uncertainty, also converted
        uncertainty_c = 2.0 * 5/9

        return value_c, uncertainty_c

class FastTemperatureSensor(TemperatureSensor):
    """
    High-speed sensor with reduced range.

    - Uncertainty: ±0.5°C
    - Range: 0 to 100°C (NARROWER than base class)
    - Supports calibration
    - Clearly documents range limitation
    """

    def __init__(self, sensor_id: str):
        # Initialize with narrower range (allowed - not wider!)
        super().__init__(sensor_id, valid_range=(0, 100))

    def _read_raw(self) -> tuple[float, float]:
        """Read from fast hardware."""
        value = 25.0 + np.random.normal(0, 0.5)
        uncertainty = 0.5
        return value, uncertainty

class UncalibratedSensor(TemperatureSensor):
    """
    Sensor that cannot be calibrated (e.g., sealed unit).

    If a sensor truly cannot be calibrated, we make this explicit
    and handle it properly rather than silently failing.
    """

    def _read_raw(self) -> tuple[float, float]:
        """Read from uncalibrated hardware."""
        value = 25.0 + np.random.normal(0, 1.0)
        uncertainty = 1.0
        return value, uncertainty

    def calibrate(self, reference_temp: float, measured_temp: float):
        """
        Uncalibrated sensors raise an error rather than silently failing.
        """
        raise NotImplementedError(
            f"Sensor {self.sensor_id} is a sealed unit and cannot be calibrated. "
            f"Consider using a different sensor model if calibration is required."
        )

# Experiment runner works correctly with ALL sensors now
class ExperimentRunner:
    """Runs an experiment with temperature monitoring."""

    def __init__(self, sensor: TemperatureSensor):
        self.sensor = sensor
        self.data = []

        # Check sensor's valid range
        min_t, max_t = sensor.get_valid_range()
        print(f"Sensor {sensor.sensor_id} valid range: {min_t}°C to {max_t}°C")

    def run_experiment(self, duration_seconds: int):
        """Collect data for specified duration."""
        print(f"Starting experiment with {self.sensor.sensor_id}")

        for i in range(duration_seconds):
            measurement = self.sensor.read()

            # Can trust all measurements are in Celsius!
            if not self.sensor.is_reading_valid(measurement):
                print(f"WARNING: Reading {measurement.value:.1f}°C outside valid range")
                continue

            # Can trust uncertainty is always present and meaningful
            if measurement.uncertainty > 1.0:
                print(f"WARNING: High uncertainty: {measurement.uncertainty:.2f}°C")

            self.data.append(measurement)

        self._analyze_results()

    def _analyze_results(self):
        """Analyze collected data."""
        if not self.data:
            print("No valid data collected!")
            return

        values = [m.value for m in self.data]
        uncertainties = [m.uncertainty for m in self.data]

        mean_temp = np.mean(values)
        mean_uncertainty = np.mean(uncertainties)

        print(f"\nResults:")
        print(f"  Mean temperature: {mean_temp:.2f}°C")
        print(f"  Mean uncertainty: {mean_uncertainty:.2f}°C")
        print(f"  Samples collected: {len(self.data)}")

# Usage - everything works correctly now!
print("=== Precision Sensor ===")
precise = PrecisionTemperatureSensor("PREC-001")
precise.calibrate(25.0, 25.5)
exp1 = ExperimentRunner(precise)
exp1.run_experiment(10)

print("\n=== Economy Sensor ===")
economy = EconomyTemperatureSensor("ECON-001")
economy.calibrate(25.0, 77.0)  # Works correctly despite F→C conversion
exp2 = ExperimentRunner(economy)
exp2.run_experiment(10)  # Results are correct!

print("\n=== Fast Sensor ===")
fast = FastTemperatureSensor("FAST-001")
exp3 = ExperimentRunner(fast)  # Range clearly documented
exp3.run_experiment(10)

print("\n=== Uncalibrated Sensor ===")
uncalibrated = UncalibratedSensor("UNCAL-001")
try:
    uncalibrated.calibrate(25.0, 26.0)  # Fails explicitly
except NotImplementedError as e:
    print(f"Expected error: {e}")
exp4 = ExperimentRunner(uncalibrated)
exp4.run_experiment(10)  # But reading still works!

Why This Is Better

1. Consistent Return Types and Units

All sensors return Measurement objects with temperature in Celsius. The economy sensor does its conversion internally.

2. Honour Preconditions and Postconditions

Precondition: Sensors can be read at any time
Postcondition: read() always returns valid Measurement with non-negative uncertainty
All subclasses honour this contract

3. Explicit About Limitations

UncalibratedSensor raises an error for calibration rather than silently failing. This seems like it violates LSP (throwing an exception the base doesn't), but there's a key distinction:

Violating LSP: Throwing exceptions for VALID inputs (e.g., raising error when calibration values are in expected range)
Honouring LSP: Throwing exceptions that indicate a capability limitation (NotImplementedError says "this operation isn't supported")

Better alternatives exist (like checking a can_calibrate() flag), but raising NotImplementedError is the pragmatic Python convention for "this subclass doesn't support this operation."

4. Range Restrictions Are Clear

The FastTemperatureSensor demonstrates an LSP-compliant way to have tighter restrictions. The base class contract allows subclasses to be MORE restrictive (narrower range, higher precision), but not LESS restrictive (wider range, lower precision).

However, this creates a practical problem: if your experiment needs to measure 150°C, the fast sensor will reject valid readings. This is LSP-compliant but might not be what you want.

The trade-off:

✅ Code doesn't silently fail (you get explicit warnings about invalid range)
✅ The contract is honored (fast sensor doesn't lie about capabilities)
❌ You still need to know which sensor is appropriate for your experiment

This is why documenting sensor capabilities and checking ranges upfront (as the ExperimentRunner class does) is critical. LSP prevents silent failures, but it doesn't eliminate the need to choose the right tool for the job.

5. No Surprises

Any code written for TemperatureSensor works correctly with any subclass.

Design by Contract

LSP is really about contracts. The base class establishes a contract:

class TemperatureSensor:
    """
    CONTRACT:

    PRECONDITIONS (what caller must ensure):
    - Sensor is properly initialized
    - For calibrate(): reference and measured temps are valid numbers

    POSTCONDITIONS (what class guarantees):
    - read() returns Measurement in Celsius
    - Uncertainty is non-negative
    - Valid range is defined
    - calibrate() adjusts future readings (or raises NotImplementedError)

    INVARIANTS (always true):
    - calibration_offset is a number
    - valid_range is a tuple of (min, max) where min < max
    """

Subclasses can:

✅ Accept weaker preconditions (be more lenient about inputs)
✅ Provide stronger postconditions (give more guarantees)
✅ Maintain all invariants

Subclasses cannot:

❌ Require stronger preconditions (be more demanding)
❌ Provide weaker postconditions (give fewer guarantees)
❌ Break invariants

For example:

# VIOLATES CONTRACT: Weaker postcondition
class UnreliableSensor(TemperatureSensor):
    def read(self) -> Measurement:
        # Sometimes returns None! Base class promises Measurement
        if self.hardware_broken:
            return None  # ❌ Breaks contract

# HONOURS CONTRACT: Stronger postcondition
class ReliableSensor(TemperatureSensor):
    def read(self) -> Measurement:
        # Always returns valid Measurement, sometimes with retry
        for attempt in range(3):
            result = self._try_read()
            if result.uncertainty < 2.0:
                return result  # ✅ Always returns valid Measurement
        return self._get_safe_default()

Real-World Consequences of LSP Violations

When you violate LSP, you create silent failures that are expensive to debug:

Timeline of a typical LSP violation disaster:

Day 1: Student A writes experiment code with PrecisionSensor, tests thoroughly, everything works
Day 30: Student B needs to run same experiment but PrecisionSensor is in use
Day 30: Student B swaps in CheapSensor (it's a subclass, should work!)
Day 31-60: Student B collects 30 days of data, code runs without errors
Day 61: Student B analyzes results, gets bizarre temperature distributions
Day 62: Student B spends hours checking analysis code (which is correct)
Day 63: Student B re-calibrates cheap sensor (doesn't help)
Day 64: Student B checks raw data files, discovers °F in the logs
Day 65: Student B realizes all 30 days of data is corrupted
Day 65: Student B restarts experiment, loses a month of work

The cost: 30+ days of wasted data collection, maybe a delayed graduation, or wasted grant funding.

The problem: The code didn't fail, it lied. If CheapSensor couldn't pretend to be a TemperatureSensor, the error would have been caught on Day 30.

Better approach: Honour the contract (convert F→C internally) or don't inherit (use a different type entirely, forcing explicit handling).

Common LSP Violations in Scientific Code

Here are two patterns that frequently violate LSP in scientific codebases, along with how to fix them:

Violation 1: Changing Precision or Format

class DataPoint:
    def get_timestamp(self) -> float:
        """Return Unix timestamp in seconds."""
        return self._timestamp

# VIOLATION: Different precision
class HighResolutionDataPoint(DataPoint):
    def get_timestamp(self) -> float:
        """Returns microsecond precision timestamp."""
        return self._timestamp_us  # ❌ Different scale! Off by 10^6

Violation 2: Different Thread-Safety Guarantees

class DataBuffer:
    def append(self, value: float):
        """Add value to buffer. Thread-safe."""
        with self._lock:
            self._data.append(value)

# VIOLATION: Removes thread-safety
class FastDataBuffer(DataBuffer):
    def append(self, value: float):
        """Add value to buffer."""
        self._data.append(value)  # ❌ No lock! Breaks in multithreaded code

Testing for LSP Compliance

Write tests that work for the base class and run them on all subclasses:

import unittest

class TestTemperatureSensor(unittest.TestCase):
    """Tests that should pass for ANY TemperatureSensor subclass."""

    def get_sensor(self) -> TemperatureSensor:
        """Override in subclasses to test specific sensor."""
        return PrecisionTemperatureSensor("TEST-001")

    def test_read_returns_celsius(self):
        """All sensors must return Celsius."""
        sensor = self.get_sensor()
        measurement = sensor.read()
        # Temperature in reasonable range for Celsius
        self.assertGreater(measurement.value, -100)
        self.assertLess(measurement.value, 300)

    def test_uncertainty_is_positive(self):
        """All sensors must provide non-negative uncertainty."""
        sensor = self.get_sensor()
        measurement = sensor.read()
        self.assertGreaterEqual(measurement.uncertainty, 0)

    def test_calibration_affects_readings(self):
        """Calibration should adjust readings (or raise NotImplementedError)."""
        sensor = self.get_sensor()

        try:
            before = sensor.read().value
            sensor.calibrate(before + 1.0, before)
            after = sensor.read().value
            # Should be approximately 1°C higher
            self.assertGreater(after, before + 0.5)
        except NotImplementedError:
            # Acceptable if sensor can't calibrate
            pass

# Test each subclass with the same tests
class TestPrecisionSensor(TestTemperatureSensor):
    def get_sensor(self):
        return PrecisionTemperatureSensor("PREC-TEST")

class TestEconomySensor(TestTemperatureSensor):
    def get_sensor(self):
        return EconomyTemperatureSensor("ECON-TEST")

class TestFastSensor(TestTemperatureSensor):
    def get_sensor(self):
        return FastTemperatureSensor("FAST-TEST")

# All tests should pass for all sensors!

class TestCheapSensor(TestTemperatureSensor):
    """This would FAIL if we used the bad CheapSensor implementation."""
    def get_sensor(self):
        return CheapTemperatureSensor("CHEAP-TEST")  # From "before" version

    # test_read_returns_celsius would fail!
    # measurement.value would be ~77 (Fahrenheit) instead of ~25 (Celsius)

Why this works: If all subclasses pass the same base class tests, they're substitutable. Any code written against TemperatureSensor will work with any subclass.

This is the practical test for LSP: can you swap implementations without changing calling code?

Red Flags That You're Violating LSP

Watch for these warning signs:

Subclass changes return types or data structures
Subclass returns different units than parent (Celsius vs Fahrenheit)
Subclass throws exceptions the parent doesn't
Subclass silently ignores method calls that should work
You need to check the specific type before calling methods
Documentation says "works like X except..."
Tests for base class fail on subclass
You have isinstance() checks in calling code
Subclass requires additional setup the parent doesn't

If you're checking isinstance(sensor, CheapTemperatureSensor) to handle it specially, you've violated LSP.

Common Mistakes: When Inheritance Isn't the Answer

The biggest LSP mistake: using inheritance when you should use composition.

Use inheritance for "is-a" relationships:

A PrecisionTemperatureSensor is a TemperatureSensor
A QuadraticFit is a FitStrategy
Both implement the same contract completely

Use composition for "has-a" relationships:

A DataAcquisitionSystem has a sensor (not "is a" sensor)
An Experiment has a data processor (not "is a" processor)

# Instead of inheriting, compose!
class DataAcquisitionSystem:
    def __init__(self, sensor: TemperatureSensor,
                 storage: DataStorage,
                 processor: SignalProcessor):
        self.sensor = sensor
        self.storage = storage
        self.processor = processor

    def acquire_data(self):
        measurement = self.sensor.read()
        processed = self.processor.process(measurement)
        self.storage.save(processed)

If you find yourself thinking:

"It's like X but..."
"It mostly works like X except..."
"It's X with these limitations..."

→ You probably need composition, not inheritance.

Practical Guidelines

The Liskov Substitution Principle says: Subclasses must be substitutable for their base classes without breaking the program.

Following LSP in scientific code:

Ensures equipment/algorithms are truly interchangeable
Prevents subtle bugs from "almost compatible" implementations
Makes testing easier (test base class, trust subclasses)
Clarifies design decisions (inheritance vs. composition)
Documents contracts explicitly

The key insight: Inheritance creates a promise. The subclass must keep that promise completely, not just partially.

Before creating a subclass, ask:

Does the subclass strengthen the base class contract? ✅ OK
Does it weaken the contract in any way? ❌ Violates LSP
Does it change types, units, or conventions? ❌ Violates LSP
Would code written for the base class break with this subclass? ❌ Violates LSP

If you answer "no" to question 1 or "yes" to questions 2-4, consider:

Using composition instead of inheritance
Creating a separate class hierarchy
Making the differences explicit in the type system

Example: Does it weaken the contract?

Base class: process(data) accepts any numpy array

Subclass: process(data) requires power-of-2 length

→ ❌ Violates LSP (strengthened precondition)

Example: Does it change units?

Base class: get_distance() returns meters

Subclass: get_distance() returns millimeters

→ ❌ Violates LSP (changed postcondition)

When Pragmatism Trumps Perfect Substitutability

LSP is a guideline, not an absolute law. Sometimes you need to make trade-offs:

Performance-critical code: If a specialized subclass can be 10x faster by breaking strict substitutability, and the performance matters more than perfect polymorphism, document the limitation clearly and accept the trade-off.

Prototyping and exploration: When you're exploring a problem, strict LSP compliance can slow you down. Get it working first, refactor for substitutability later if you need multiple implementations.

Legacy integration: When wrapping third-party hardware or libraries that don't follow your contracts, sometimes an adapter that partially violates LSP is better than no integration at all.

The key: Make violations explicit, document them clearly, and refactor toward compliance when the code stabilizes.

Performance Notes

Following LSP doesn't add performance overhead. The cost of method calls and inheritance is negligible compared to actual sensor reads, data processing, or I/O operations.

The real performance benefit: you can optimize one implementation without affecting others. Want a faster sensor class? Create one that follows the contract. No need to modify existing code.

Your Turn

Find a place in your code where you use inheritance
Write tests for the base class (use the pattern shown in "Testing for LSP Compliance")
Run those tests on all subclasses
If any fail, you've found an LSP violation
Refactor to either fix the violation or remove the inheritance

In the next post, we'll explore the Interface Segregation Principle: why forcing classes to implement methods they don't need causes problems, and how to fix it.

Have you been surprised by a subclass that didn't work like you expected? Share your story in the comments!

Previous posts in this series:

Next in this series:

Interface Segregation Principle for Scientists - Coming next week

Extending Without Breaking: Adding New Analysis Methods Safely

Rob Johnston — Mon, 12 Jan 2026 14:00:00 +0000

Part 2 of the SOLID Principles for Scientific Programmers series

The Validation Nightmare

You've spent six months developing and validating a data analysis pipeline for your research. Your advisor signed off on the methodology. You've compared results with published benchmarks. The code works perfectly, and you've already published one paper using it.

Then you need to add a new fitting algorithm to compare with your current approach. You open the code, find the analysis section, and add an elif statement. Simple enough, right?

But now you have to re-validate everything. Did your change accidentally affect the existing algorithm? Did you introduce a subtle bug in the control flow? Your advisor insists you re-run all the validation tests before you can use the code again for publication.

You just wanted to add a feature, not risk breaking what already works.

This is the problem the Open/Closed Principle (OCP) solves.

What Is the Open/Closed Principle?

Bertrand Meyer originally stated it as:

Software entities should be open for extension, but closed for modification. ¹

In practical terms: You should be able to add new features (open for extension) without changing existing, tested, working code (closed for modification).

Think of it like adding a new instrument to your lab. You don't rewire the entire electrical system—you plug it into an existing outlet. The infrastructure is designed to accommodate new equipment without modification.

Before You Refactor: Is It Worth It?

OCP requires upfront design work. Before refactoring, consider:

How often do you add new fitting methods? If rarely, a simple if-elif is fine
Is the code validated and published? OCP protects published results
Do multiple people work on it? Multiple contributors benefit most from OCP
Would breaking existing methods be catastrophic? High stakes justify the structure

If you answered "yes" to 2+ questions, OCP is worth implementing.

A Real Example: The Problem

Let's look at a typical data fitting pipeline. This is the kind of code that grows organically as research progresses:

import numpy as np
from scipy.optimize import curve_fit
from scipy.stats import linregress
from sklearn.linear_model import Ridge
from sklearn.preprocessing import PolynomialFeatures

class DataFitter:
    """Fits various models to experimental data."""

    def __init__(self, x_data, y_data):
        self.x_data = np.array(x_data)
        self.y_data = np.array(y_data)
        self.fit_result = None
        self.method = None

    def fit(self, method='linear'):
        """Fit data using specified method."""
        self.method = method

        if method == 'linear':
            # Simple linear regression
            slope, intercept, r_value, p_value, std_err = linregress(
                self.x_data, self.y_data
            )
            self.fit_result = {
                'params': [intercept, slope],
                'r_squared': r_value**2,
                'method': 'linear'
            }

        elif method == 'quadratic':
            # Quadratic polynomial fit
            params = np.polyfit(self.x_data, self.y_data, 2)
            predictions = np.polyval(params, self.x_data)
            ss_res = np.sum((self.y_data - predictions)**2)
            ss_tot = np.sum((self.y_data - np.mean(self.y_data))**2)
            r_squared = 1 - (ss_res / ss_tot)
            self.fit_result = {
                'params': params,
                'r_squared': r_squared,
                'method': 'quadratic'
            }

        elif method == 'exponential':
            # Exponential fit: y = a * exp(b * x)
            def exp_func(x, a, b):
                return a * np.exp(b * x)

            params, _ = curve_fit(exp_func, self.x_data, self.y_data)
            predictions = exp_func(self.x_data, *params)
            ss_res = np.sum((self.y_data - predictions)**2)
            ss_tot = np.sum((self.y_data - np.mean(self.y_data))**2)
            r_squared = 1 - (ss_res / ss_tot)
            self.fit_result = {
                'params': params,
                'r_squared': r_squared,
                'method': 'exponential'
            }

        elif method == 'power':
            # Power law fit: y = a * x^b
            # Use log-log transformation
            log_x = np.log(self.x_data)
            log_y = np.log(self.y_data)
            slope, intercept, r_value, _, _ = linregress(log_x, log_y)
            a = np.exp(intercept)
            b = slope
            self.fit_result = {
                'params': [a, b],
                'r_squared': r_value**2,
                'method': 'power'
            }

        elif method == 'ridge':
            # Ridge regression for regularization
            from sklearn.preprocessing import PolynomialFeatures
            poly = PolynomialFeatures(degree=3)
            X_poly = poly.fit_transform(self.x_data.reshape(-1, 1))

            ridge = Ridge(alpha=1.0)
            ridge.fit(X_poly, self.y_data)

            predictions = ridge.predict(X_poly)
            ss_res = np.sum((self.y_data - predictions)**2)
            ss_tot = np.sum((self.y_data - np.mean(self.y_data))**2)
            r_squared = 1 - (ss_res / ss_tot)

            self.fit_result = {
                'params': ridge.coef_,
                'r_squared': r_squared,
                'method': 'ridge'
            }
        else:
            raise ValueError(f"Unknown method: {method}")

        return self.fit_result

    def predict(self, x_new):
        """Make predictions using the fitted model."""
        if self.fit_result is None:
            raise ValueError("Must fit model first")

        x_new = np.array(x_new)

        # More if-elif chains for prediction
        if self.method == 'linear':
            intercept, slope = self.fit_result['params']
            return intercept + slope * x_new

        elif self.method == 'quadratic':
            return np.polyval(self.fit_result['params'], x_new)

        elif self.method == 'exponential':
            a, b = self.fit_result['params']
            return a * np.exp(b * x_new)

        elif self.method == 'power':
            a, b = self.fit_result['params']
            return a * x_new**b

        elif self.method == 'ridge':
            from sklearn.preprocessing import PolynomialFeatures
            poly = PolynomialFeatures(degree=3)
            X_poly = poly.fit_transform(x_new.reshape(-1, 1))
            # Wait, we don't have the ridge object anymore!
            raise NotImplementedError("Ridge prediction not available after fitting")

        raise ValueError(f"Unknown method: {self.method}")

    def get_residuals(self):
        """Calculate fit residuals."""
        predictions = self.predict(self.x_data)
        return self.y_data - predictions

    def plot(self, title=None):
        """Plot the original data and fitted curve."""
        import matplotlib.pyplot as plt

        # Create a dense x range for smooth curve
        x_smooth = np.linspace(self.x_data.min(), self.x_data.max(), 100)
        y_smooth = self.predict(x_smooth)

        plt.figure(figsize=(10, 6))
        plt.scatter(self.x_data, self.y_data, label='Data', s=50, alpha=0.7)
        plt.plot(x_smooth, y_smooth, 'r-', label=f'{self.method.capitalize()} fit', linewidth=2)
        plt.xlabel('X')
        plt.ylabel('Y')
        plt.legend()
        plt.grid(True, alpha=0.3)
        plt.title(title or f'{self.method.capitalize()} Fit (R² = {self.fit_result["r_squared"]:.3f})')
        plt.tight_layout()
        plt.show()

    def compare_methods(self, methods):
        """Compare R² values across multiple fitting methods."""
        results = {}
        for method in methods:
            try:
                fit_result = self.fit(method)
                results[method] = fit_result['r_squared']
            except Exception as e:
                print(f"Warning: Method '{method}' failed: {e}")
                results[method] = None
        return results

# Usage
x_data = np.array([-3, -2, -1, 0, 1, 2, 3, 4, 5, 6])
y_data = np.array([9.2, 6.1, 3.7, 2.0, 1.6, 1.8, 3.8, 6.0, 9.7, 13.5])
fitter = DataFitter(x_data, y_data)

# Compare multiple strategies
print("\nComparing multiple fitting methods:")
methods_to_compare = ['linear', 'quadratic', 'exponential', 'power', 'ridge']
comparison_results = fitter.compare_methods(methods_to_compare)
for method_name, r_squared in comparison_results.items():
    print(f"{method_name:15s}: R² = {r_squared:.3f}")

# Try a single method - pass string and plot it
result = fitter.fit('quadratic')
fitter.plot()
print(f"R² = {result['r_squared']:.3f}")

Problems with This Design

Every time you want to add a new fitting method, you must:

Modify the fit() method - add another elif branch
Modify the predict() method - add corresponding prediction logic
Risk breaking existing methods - any change could introduce bugs
Re-test everything - you can't be sure you didn't break something
Deal with growing complexity - the methods get longer and harder to understand
Struggle with state management - some methods (like ridge) can't even be implemented correctly because the design doesn't maintain necessary state

The code becomes increasingly fragile. What if you typo 'linear' as 'liner' somewhere? What if the new method needs different return values? Each addition increases the risk of breaking validated code.

And did you notice the bug in ridge prediction?

elif self.method == 'ridge':
    # ...
    raise NotImplementedError("Ridge prediction not available after fitting")

The original design can't even implement ridge prediction correctly because it doesn't maintain the necessary state. This is a design failure that OCP prevents—each strategy naturally encapsulates its own state.

The Solution: Open/Closed Principle

This solves the validation nightmare: when you add a new fitting method, existing methods remain unchanged and don't require re-validation.

Let's refactor this using OCP. The key insight: Define an interface for fitting, then create separate classes for each method.

BEFORE:                          AFTER:
┌──────────────┐                ┌─────────────┐
│ DataFitter   │                │ FitStrategy │ (abstract)
│              │                └─────────────┘
│ fit():       │                       ↑
│   if linear  │                 (implements)
│   elif quad  │         ┌─────────────┼─────────────┐
│   elif exp   │         │             │             │
│   elif power │    ┌────────┐   ┌─────────┐   ┌─────────────┐
│   elif ridge │    │ Linear │   │Quadratic│   │ Exponential │
│              │    └────────┘   └─────────┘   └─────────────┘
│ predict():   │
│   if linear  │    ┌───────────────┐
│   elif quad  │    │ DataFitter    │ (uses implementations)
│   elif exp   │    │ (orchestrator)│
│   ...        │    └───────────────┘
└──────────────┘

import numpy as np
from abc import ABC, abstractmethod
from scipy.optimize import curve_fit
from scipy.stats import linregress
from sklearn.linear_model import Ridge
from sklearn.preprocessing import PolynomialFeatures

# ABSTRACTION: What all fitting methods must provide
class FitStrategy(ABC):
    """Abstract base class for fitting strategies."""

    @abstractmethod
    def fit(self, x_data, y_data):
        """Fit the model and return params and r_squared."""
        pass

    @abstractmethod
    def predict(self, params, x_new):
        """Predict using the fitted params."""
        pass

    @property
    @abstractmethod
    def name(self):
        """Return the name of the strategy."""
        pass

# CONCRETE IMPLEMENTATIONS: Each method in its own class

class LinearFit(FitStrategy):
    """Linear regression fitting strategy."""

    def fit(self, x_data, y_data):
        slope, intercept, r_value, _, _ = linregress(x_data, y_data)
        return {'params': [intercept, slope], 'r_squared': r_value**2}

    def predict(self, params, x_new):
        intercept, slope = params
        return intercept + slope * x_new

    @property
    def name(self):
        return 'linear'


class QuadraticFit(FitStrategy):
    """Quadratic polynomial fitting strategy."""

    def fit(self, x_data, y_data):
        params = np.polyfit(x_data, y_data, 2)
        predictions = np.polyval(params, x_data)
        ss_res = np.sum((y_data - predictions)**2)
        ss_tot = np.sum((y_data - np.mean(y_data))**2)
        r_squared = 1 - (ss_res / ss_tot)
        return {'params': params, 'r_squared': r_squared}

    def predict(self, params, x_new):
        return np.polyval(params, x_new)

    @property
    def name(self):
        return 'quadratic'


class ExponentialFit(FitStrategy):
    """Exponential fit strategy: y = a * exp(b * x)."""

    def fit(self, x_data, y_data):
        def exp_func(x, a, b):
            return a * np.exp(b * x)

        params, _ = curve_fit(exp_func, x_data, y_data)
        predictions = exp_func(x_data, *params)
        ss_res = np.sum((y_data - predictions)**2)
        ss_tot = np.sum((y_data - np.mean(y_data))**2)
        r_squared = 1 - (ss_res / ss_tot)
        return {'params': params, 'r_squared': r_squared}

    def predict(self, params, x_new):
        a, b = params
        return a * np.exp(b * x_new)

    @property
    def name(self):
        return 'exponential'


class PowerFit(FitStrategy):
    """Power law fit strategy: y = a * x^b."""

    def fit(self, x_data, y_data):
        log_x = np.log(x_data)
        log_y = np.log(y_data)
        slope, intercept, r_value, _, _ = linregress(log_x, log_y)
        a = np.exp(intercept)
        b = slope
        return {'params': [a, b], 'r_squared': r_value**2}

    def predict(self, params, x_new):
        a, b = params
        return a * x_new**b

    @property
    def name(self):
        return 'power'


class RidgeFit(FitStrategy):
    """Ridge regression fitting strategy."""

    def __init__(self, degree=3, alpha=1.0):
        self.degree = degree
        self.alpha = alpha
        self.poly = None
        self.ridge = None

    def fit(self, x_data, y_data):
        self.poly = PolynomialFeatures(degree=self.degree)
        X_poly = self.poly.fit_transform(x_data.reshape(-1, 1))

        self.ridge = Ridge(alpha=self.alpha)
        self.ridge.fit(X_poly, y_data)

        predictions = self.ridge.predict(X_poly)
        ss_res = np.sum((y_data - predictions)**2)
        ss_tot = np.sum((y_data - np.mean(y_data))**2)
        r_squared = 1 - (ss_res / ss_tot)
        return {'params': self.ridge.coef_, 'r_squared': r_squared}

    def predict(self, params, x_new):
        X_poly = self.poly.fit_transform(x_new.reshape(-1, 1))
        return self.ridge.predict(X_poly)

    @property
    def name(self):
        return 'ridge'

# ORCHESTRATOR: Uses fitting methods without knowing their details
class DataFitter:
    """Fits data using various methods following Open/Closed Principle."""

    def __init__(self, x_data, y_data):
        self.x_data = np.array(x_data)
        self.y_data = np.array(y_data)
        self.fit_result = None
        self.strategy = None

    def fit(self, strategy):
        """Fit data using the provided strategy object."""
        self.strategy = strategy
        self.fit_result = strategy.fit(self.x_data, self.y_data)
        self.fit_result['method'] = strategy.name
        return self.fit_result

    def predict(self, x_new):
        """Make predictions using the fitted model."""
        if self.strategy is None:
            raise ValueError("Must fit model first")

        x_new = np.array(x_new)
        return self.strategy.predict(self.fit_result['params'], x_new)

    def get_residuals(self):
        """Calculate fit residuals."""
        predictions = self.predict(self.x_data)
        return self.y_data - predictions

    def plot(self, title=None):
        """Plot the original data and fitted curve."""
        import matplotlib.pyplot as plt

        # Create a dense x range for smooth curve
        x_smooth = np.linspace(self.x_data.min(), self.x_data.max(), 100)
        y_smooth = self.predict(x_smooth)

        plt.figure(figsize=(10, 6))
        plt.scatter(self.x_data, self.y_data, label='Data', s=50, alpha=0.7)
        plt.plot(x_smooth, y_smooth, 'r-', label=f'{self.strategy.name.capitalize()} fit', linewidth=2)
        plt.xlabel('X')
        plt.ylabel('Y')
        plt.legend()
        plt.grid(True, alpha=0.3)
        plt.title(title or f'{self.strategy.name.capitalize()} Fit (R² = {self.fit_result["r_squared"]:.3f})')
        plt.tight_layout()
        plt.show()

    def compare_methods(self, strategies):
        """Compare multiple fitting strategies and return their R² values."""
        results = {}
        for strategy in strategies:
            fit_result = strategy.fit(self.x_data, self.y_data)
            results[strategy.name] = fit_result['r_squared']

        return results

# USAGE: clean and extensible!
x_data = np.array([-3, -2, -1, 0, 1, 2, 3, 4, 5, 6])
y_data = np.array([9.2, 6.1, 3.7, 2.0, 1.6, 1.8, 3.8, 6.0, 9.7, 13.5])
fitter = DataFitter(x_data, y_data)

# Compare multiple strategies easily
print("\nComparing multiple fitting methods:")
strategies = [LinearFit(), QuadraticFit(), ExponentialFit(), PowerFit(), RidgeFit()]
comparison_results = fitter.compare_methods(strategies)
for method_name, r_squared in comparison_results.items():
    print(f"{method_name:15s}: R² = {r_squared:.3f}")

# Try a single method - pass strategy object and plot it
result = fitter.fit(QuadraticFit())
fitter.plot()
print(f"R² = {result['r_squared']:.3f}")

Why This Is Better

1. Easy to Extend

Want to add a new fitting method? Just create a new class:

class LogarithmicFit(FitStrategy):
    """Logarithmic fit strategy: y = a + b * ln(x)."""

    def fit(self, x_data, y_data):
        # Transform: y = a + b * ln(x)
        # Fit as: y = a + b * x_log, where x_log = ln(x)
        log_x = np.log(x_data)
        slope, intercept, r_value, _, _ = linregress(log_x, y_data)
        # slope is 'b', intercept is 'a'
        return {'params': [intercept, slope], 'r_squared': r_value**2}

    def predict(self, params, x_new):
        a, b = params
        return a + b * np.log(x_new)

    @property
    def name(self):
        return 'logarithmic'

# Use it immediately without changing any existing code!
fitter = DataFitter(x_data, y_data)
result = fitter.fit(LogarithmicFit())

No modification to:

DataFitter class
Any existing fitting methods
Any existing tests
Any validated code

2. Isolated Testing

When you add LogarithmicFit, you don't need to re-run the tests for ExponentialFit. Why? Because ExponentialFit wasn't modified—its code is identical to the validated version.

Each strategy can be tested independently:

import unittest

class TestExponentialFit(unittest.TestCase):
    def test_perfect_exponential_data(self):
        """Test with data that perfectly follows exponential curve."""
        x = np.linspace(0, 5, 50)
        y_true = 2.0 * np.exp(0.5 * x)

        strategy = ExponentialFit()
        result = strategy.fit(x, y_true)

        # Should fit nearly perfectly
        self.assertGreater(result['r_squared'], 0.99)

        # Parameters should be close to true values
        a, b = result['params']
        self.assertAlmostEqual(a, 2.0, places=1)
        self.assertAlmostEqual(b, 0.5, places=1)

class TestLogarithmicFit(unittest.TestCase):
    def test_new_method(self):
        """Test the new logarithmic fit thoroughly."""
        # Extensive tests for the new method
        # Old tests never need to run!
        pass

In the if-elif version, every addition modifies the central fit() method, requiring full re-validation of all methods.

3. Type safety and IDE Support

Before:

fitter.fit('liner')  # Typo! Runtime error

After:

fitter.fit(LinearFit())  # IDE catches if LinearFit doesn't exist

4. Protects Validated Code

Remember the validation nightmare from the opening? With OCP, when you add LogarithmicFit:

✅ LinearFit code: unchanged → validation still valid
✅ QuadraticFit code: unchanged → validation still valid
✅ ExponentialFit code: unchanged → validation still valid
✅ Your published results: safe

You only need to validate the new method. Your advisor can approve the addition without requiring full re-validation of the entire pipeline.

Red Flags that you need OCP

Ask yourself: "Can I add a new variant without modifying existing files?" If the answer is no, watch for these warning signs:

Long if-elif or switch statements (>3 branches)
Adding a variant requires editing multiple locations
Similar code duplicated across branches
String-based method selection ('linear', 'quadratic', etc.)
Tests that must re-run everything after any change
Validated code that you're afraid to touch
Methods that can't be fully implemented (like the ridge bug)

Common Mistakes: When Not to Use OCP

Don't create this structure for:

❌ Simple, stable code:

# Don't need OCP for basic statistics
def calculate_stats(data):
    return {
        'mean': np.mean(data),
        'std': np.std(data),
        'median': np.median(data)
    }
# This is stable, simple, and unlikely to expand

❌ Code you'll use once:

# Exploratory analysis - keep it simple!
if method == 'a':
    result = approach_a()
elif method == 'b':
    result = approach_b()
# Throwaway code doesn't need robust architecture

✅ Do use OCP when:

You expect to add new algorithms/methods regularly
The code is validated and shouldn't be modified
Multiple people work on the same codebase
Users need to provide their own implementations
Different methods need different configuration

Performance Notes

Creating strategy objects has negligible overhead compared to the actual fitting computations. The real cost is in curve_fit(), polyfit(), and statistical calculations, not object instantiation.

Your Turn

Find a place in your code with a long if-elif chain
Identify what varies between the branches
Create an abstract interface for that variation
Extract one branch into a class
Test that it works
Extract the remaining branches one at a time

In the next post, we'll explore the Liskov Substitution Principle: ensuring that your extended classes can truly substitute for their base classes without breaking things.

Have you been bitten by modifying validated code? Share your experiences in the comments!

Previous posts in this series:

Single Responsibility Principle for Scientists

Next in this series:

Liskov Substitution Principle for Scientists - Coming next week

Meyer, Bertrand, Object-Oriented Software Construction (paid link). Prentice Hall, 1988. ↩

One Class, One Job: Managing Scientific Code Complexity

Rob Johnston — Mon, 05 Jan 2026 14:00:00 +0000

Part 1 of the SOLID Principles for Scientific Programmers series

The Monolithic Monster

You started with a simple Python script to analyze some experimental data. A few hundred lines to load a CSV file, clean the data, run some statistics, and generate a plot. It worked perfectly!

Then your collaborator asked if you could add error bars. Then your advisor wanted the plots in a different format. Then you needed to support a different instrument's output format. Then someone found a bug in the outlier detection, and fixing it somehow broke the plotting code. Six months later, you have a 2,000-line file called analysis.py that nobody wants to touch because changing anything might break everything.

Sound familiar?

This is what happens when code lacks the Single Responsibility Principle (SRP): the first and most fundamental of the SOLID principles.

What Is the Single Responsibility Principle?

Robert C. Martin (Uncle Bob) originally stated it as:

A class should have only one reason to change. ¹

He later clarified what he meant by 'reason to change'. In a 2014 blog post, he stated:

Gather together the things that change for the same reasons. Separate those things that change for different reasons. ²

More practically for scientists: Each piece of code should do one thing and do it well. When you need to modify your code, you should be able to pinpoint exactly where to make the change, and that change shouldn't have ripple effects throughout your entire codebase.

SRP applies equally well to procedural scripts. Even if you don't use classes, separating file loading, processing, plotting, and exporting into different modules or functions still yields the same benefits.

Before You Refactor: Is It Worth It?

Before we dive into the solution, let's talk about when this is worth doing. SRP takes time to implement, usually 10–30 minutes to extract a small responsibility into a function or class. Don't refactor everything at once. Prioritize based on:

How often does the code change? High-change code benefits most from SRP
How many people work on it? Team code needs clearer boundaries
How long will it be maintained? Throwaway scripts don't need perfect structure
Is it causing real pain? If it works and nobody is suffering, maybe leave it alone

A Real Example: The Problem

Let's look at what could be a typical spectroscopy analysis script. Don't worry about understanding every detail—focus on the structure and the tangled responsibilities. These concepts apply to any object-oriented language.

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
from scipy import signal, stats
import os

class SpectroscopyAnalysis:
    """Does everything for spectroscopy analysis."""

    def __init__(self, filename):
        self.filename = filename
        self.data = None
        self.processed_data = None
        self.peaks = None
        self.results = {}

    def run_complete_analysis(self):
        """Run the entire analysis pipeline."""

        # Load data from CSV
        print(f"Loading data from {self.filename}")
        try:
            self.data = pd.read_csv(self.filename, skiprows=2)
            # Handle different column names from different instruments
            if 'Wavelength' in self.data.columns:
                self.data.rename(columns={'Wavelength': 'wavelength',
                                         'Intensity': 'intensity'}, inplace=True)
            elif 'wl' in self.data.columns:
                self.data.rename(columns={'wl': 'wavelength',
                                         'int': 'intensity'}, inplace=True)
        except Exception as e:
            print(f"Error loading file: {e}")
            return None

        # Remove baseline
        print("Processing data...")
        baseline = np.polyfit(self.data['wavelength'],
                             self.data['intensity'], 2)
        baseline_curve = np.polyval(baseline, self.data['wavelength'])
        self.data['corrected'] = self.data['intensity'] - baseline_curve

        # Remove outliers
        z_scores = np.abs(stats.zscore(self.data['corrected']))
        self.data = self.data[z_scores < 3]

        # Smooth data
        self.processed_data = signal.savgol_filter(
            self.data['corrected'], 51, 3
        )

        # Find peaks
        print("Finding peaks...")
        peak_indices, properties = signal.find_peaks(
            self.processed_data,
            height=np.mean(self.processed_data) + 2*np.std(self.processed_data),
            distance=20
        )
        self.peaks = self.data.iloc[peak_indices]['wavelength'].values

        # Calculate statistics
        print("Calculating statistics...")
        self.results['mean_intensity'] = np.mean(self.processed_data)
        self.results['std_intensity'] = np.std(self.processed_data)
        self.results['num_peaks'] = len(self.peaks)
        self.results['peak_positions'] = self.peaks
        self.results['peak_intensities'] = self.processed_data[peak_indices]

        # Generate plots
        print("Generating plots...")
        fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 8))

        # Raw data plot
        ax1.plot(self.data['wavelength'], self.data['intensity'],
                'b-', label='Raw', alpha=0.5)
        ax1.plot(self.data['wavelength'], baseline_curve,
                'r--', label='Baseline')
        ax1.set_xlabel('Wavelength (nm)')
        ax1.set_ylabel('Intensity (a.u.)')
        ax1.legend()
        ax1.set_title(f'Analysis of {os.path.basename(self.filename)}')

        # Processed data plot
        ax2.plot(self.data['wavelength'], self.processed_data, 'g-')
        ax2.plot(self.peaks, self.processed_data[peak_indices],
                'ro', label='Peaks')
        ax2.set_xlabel('Wavelength (nm)')
        ax2.set_ylabel('Corrected Intensity (a.u.)')
        ax2.legend()

        plt.tight_layout()

        # Save plot
        output_filename = self.filename.replace('.csv', '_analysis.png')
        plt.savefig(output_filename, dpi=300)
        print(f"Plot saved to {output_filename}")

        # Save results to file
        results_filename = self.filename.replace('.csv', '_results.txt')
        with open(results_filename, 'w') as f:
            f.write("Spectroscopy Analysis Results\n")
            f.write("="*50 + "\n")
            f.write(f"File: {self.filename}\n")
            f.write(f"Number of peaks: {self.results['num_peaks']}\n")
            f.write(f"Mean intensity: {self.results['mean_intensity']:.2f}\n")
            f.write(f"Std intensity: {self.results['std_intensity']:.2f}\n")
            f.write("\nPeak positions (nm):\n")
            for i, (pos, intensity) in enumerate(zip(self.results['peak_positions'],
                                                     self.results['peak_intensities'])):
                f.write(f"  Peak {i+1}: {pos:.2f} nm (intensity: {intensity:.2f})\n")
        print(f"Results saved to {results_filename}")

        return self.results

# Usage
analysis = SpectroscopyAnalysis('sample_spectrum.csv')
results = analysis.run_complete_analysis()

This code works, but it's a nightmare to maintain. Let's count the responsibilities:

File I/O: Loading CSV files with different formats
Data validation: Handling missing columns, errors
Baseline correction: Polynomial fitting and subtraction
Outlier removal: Z-score filtering
Smoothing: Savitzky-Golay filter
Peak detection: Finding and characterizing peaks
Statistical analysis: Computing summary statistics
Plotting: Creating visualizations
Report generation: Saving results to text files

That's at least 9 different reasons this class might need to change!

Why This Is a Problem

Scenario 1: Your collaborator needs to change the plot style (use different colors, add a legend in a different position).

Problem: The plotting code is tangled with data processing. You have to read through the entire method to find the plotting section.

Scenario 2: You want to use the same peak detection on a different type of data (Raman instead of infrared absorption).

Problem: The peak detection is hardwired to this specific class. You'd have to copy-paste the code or run the entire analysis pipeline.

Scenario 3: You need to support a new instrument's file format.

Problem: The file loading logic is mixed with column renaming and error handling, all in one giant method.

Scenario 4: A bug in the baseline correction is causing problems.

Problem: Fixing the baseline might accidentally break the plotting code because they're in the same method.

The Solution: Single Responsibility Principle

Let's refactor this into classes that each have a single, well-defined responsibility:

⚠️
This example is intentionally large. Don't refactor everything at once. Start with the biggest pain points. SRP is iterative, not all-or-nothing.

BEFORE:                    AFTER:
┌─────────────────────┐   ┌──────────┐  ┌───────────┐
│ SpectroscopyAnalysis│   │  Loader  │  │ Processor │
│ - loads             │   └──────────┘  └───────────┘
│ - validates         │   ┌──────────┐  ┌───────────┐
│ - processes         │   │  Peaks   │  │   Stats   │
│ - finds peaks       │   └──────────┘  └───────────┘
│ - plots             │   ┌──────────┐  ┌───────────┐
│ - saves             │   │ Plotter  │  │ Exporter  │
│ (9 responsibilities)│   └──────────┘  └───────────┘
└─────────────────────┘         ↓
                         ┌───────────────┐
                         │   Pipeline    │
                         │ (orchestrator)│
                         └───────────────┘

This is an illustrative refactor, not a prescription. You don't need all of these classes immediately—this is the destination, not the starting point. Real-world SRP often involves moving 50 lines of code at a time.

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
from scipy import signal, stats
import os

# ------------------------------------------------------
# 1. Data Loading (Single Responsibility)
# ------------------------------------------------------
class SpectraLoader:
    def load(self, filename: str) -> pd.DataFrame:
        df = pd.read_csv(filename, skiprows=2)

        # Normalize column names
        if 'Wavelength' in df.columns:
            df = df.rename(columns={'Wavelength': 'wavelength',
                                   'Intensity': 'intensity'})
        elif 'wl' in df.columns:
            df = df.rename(columns={'wl': 'wavelength',
                                   'int': 'intensity'})
        return df


# ------------------------------------------------------
# 2. Preprocessing Pipeline (Baseline, Outliers, Smoothing)
# ------------------------------------------------------
class SpectraPreprocessor:
    def preprocess(self, df: pd.DataFrame) -> tuple[pd.DataFrame, np.ndarray, np.ndarray]:
        # Baseline removal
        baseline = np.polyfit(df['wavelength'], df['intensity'], 2)
        baseline_curve = np.polyval(baseline, df['wavelength'])
        df['corrected'] = df['intensity'] - baseline_curve

        # Outlier removal
        z = np.abs(stats.zscore(df['corrected']))
        df = df[z < 3]

        # Smoothing
        smoothed = signal.savgol_filter(df['corrected'], 51, 3)
        return df, baseline_curve, smoothed


# ------------------------------------------------------
# 3. Peak Detection
# ------------------------------------------------------
class PeakDetector:
    def detect(self, wavelengths: np.ndarray, smoothed: np.ndarray):
        peak_indices, _ = signal.find_peaks(
            smoothed,
            height=np.mean(smoothed) + 2*np.std(smoothed),
            distance=20
        )
        return peak_indices, wavelengths[peak_indices]


# ------------------------------------------------------
# 4. Statistics Computation
# ------------------------------------------------------
class SpectraStats:
    def compute(self, smoothed: np.ndarray, peak_indices, peak_positions):
        return {
            "mean_intensity": float(np.mean(smoothed)),
            "std_intensity": float(np.std(smoothed)),
            "num_peaks": len(peak_positions),
            "peak_positions": peak_positions,
            "peak_intensities": smoothed[peak_indices],
        }


# ------------------------------------------------------
# 5. Plotting Responsibility
# ------------------------------------------------------
class SpectraPlotter:
    def save_plot(self, filename, df, baseline_curve, smoothed, peaks, peak_indices):
        fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 8))

        # Raw data
        ax1.plot(df['wavelength'], df['intensity'], 'b-', alpha=0.5, label='Raw')
        ax1.plot(df['wavelength'], baseline_curve, 'r--', label='Baseline')
        ax1.legend()
        ax1.set_title(f"Analysis of {os.path.basename(filename)}")

        # Processed
        ax2.plot(df['wavelength'], smoothed, 'g-', label='Corrected')
        ax2.plot(peaks, smoothed[peak_indices], 'ro', label='Peaks')
        ax2.legend()

        plt.tight_layout()
        out = filename.replace(".csv", "_analysis.png")
        plt.savefig(out, dpi=300)
        return out


# ------------------------------------------------------
# 6. Results Saving Responsibility
# ------------------------------------------------------
class SpectraResultWriter:
    def save(self, filename: str, results: dict):
        out = filename.replace(".csv", "_results.txt")
        with open(out, "w") as f:
            f.write("Spectroscopy Analysis Results\n")
            f.write("="*50 + "\n")
            f.write(f"File: {filename}\n")
            f.write(f"Number of peaks: {results['num_peaks']}\n")
            f.write(f"Mean intensity: {results['mean_intensity']:.2f}\n")
            f.write(f"Std intensity: {results['std_intensity']:.2f}\n\n")
            f.write("Peak positions (nm):\n")
            for i, (pos, intensity) in enumerate(
                zip(results["peak_positions"], results["peak_intensities"])
            ):
                f.write(f"  Peak {i+1}: {pos:.2f} nm (intensity: {intensity:.2f})\n")
        return out


# ------------------------------------------------------
# 7. Orchestrator (Does NOT do analysis)
# ------------------------------------------------------
class SpectroscopyAnalysis:
    """
    Responsible ONLY for orchestration.
    Does not compute, plot, or load anything itself.
    """

    def __init__(self):
        self.loader = SpectraLoader()
        self.preprocessor = SpectraPreprocessor()
        self.detector = PeakDetector()
        self.stats = SpectraStats()
        self.plotter = SpectraPlotter()
        self.writer = SpectraResultWriter()

    def run(self, filename):
        df = self.loader.load(filename)

        df, baseline_curve, smoothed = self.preprocessor.preprocess(df)

        peak_indices, peak_positions = self.detector.detect(
            df['wavelength'].values, smoothed
        )

        results = self.stats.compute(smoothed, peak_indices, peak_positions)

        plot_file = self.plotter.save_plot(
            filename, df, baseline_curve, smoothed, peak_positions, peak_indices
        )

        results_file = self.writer.save(filename, results)

        results["plot_file"] = plot_file
        results["results_file"] = results_file
        return results


# Usage
analysis = SpectroscopyAnalysis()
results = analysis.run("sample_spectrum.csv")

Why This Is Better

1. Easy to Modify Individual Components

Want to change the plot style? Only touch SpectrumPlotter:

class CustomPlotter(SpectrumPlotter):
    """Custom plotting style for publications."""

    def plot_analysis(self, raw_spectrum, processed_spectrum, peaks, title):
        # Use your preferred style
        plt.style.use('seaborn-paper')
        fig, ax = plt.subplots(figsize=(6, 4))
        # Custom implementation
        return fig

# Use it
pipeline = SpectroscopyPipeline()
pipeline.plotter = CustomPlotter()  # Easy swap!

2. Easy to Reuse Components

Want to use the peak finder on different data?

# Works with any Spectrum object!
finder = PeakFinder()
peaks = finder.find_peaks(my_raman_spectrum)
peaks = finder.find_peaks(my_xrd_pattern)

3. Easy to Test

Each component can be tested independently with synthetic data—no real files, no real instruments, no complex setup. For example:

import unittest

class TestPeakFinder(unittest.TestCase):
    def test_finds_obvious_peak(self):
        # Create synthetic data with known peak
        wavelength = np.linspace(400, 700, 100)
        intensity = np.exp(-(wavelength - 550)**2 / 100)
        spectrum = Spectrum(wavelength, intensity)

        finder = PeakFinder()
        peaks = finder.find_peaks(spectrum)

        self.assertEqual(len(peaks), 1)
        self.assertAlmostEqual(peaks[0].position, 550, delta=5)

You can test the processor with known baselines, the loader with mock files, and the statistics with hand-calculated values. In the monolithic version, testing anything required the entire pipeline to work.

4. Easy to Extend

Need to support a new file format?

class SpectrumLoader:
    def load_csv(self, filename: str) -> Spectrum:
        # existing code
        pass

    def load_json(self, filename: str) -> Spectrum:
        """New method for JSON files."""
        import json
        with open(filename) as f:
            data = json.load(f)
        return Spectrum(
            wavelength=np.array(data['wavelength']),
            intensity=np.array(data['intensity'])
        )

Need a different baseline correction method?

class SpectrumProcessor:
    def remove_baseline(self, spectrum: Spectrum, poly_order: int = 2):
        # existing polynomial method
        pass

    def remove_baseline_als(self, spectrum: Spectrum,
                           lam: float = 1e5, p: float = 0.01):
        """Alternative: Asymmetric Least Squares baseline."""
        # New implementation
        pass

5. Clear Documentation and Understanding

Each class has a single, clear purpose:

SpectrumLoader: "I load spectra from files"
SpectrumProcessor: "I clean and process spectrum data"
PeakFinder: "I find peaks in spectra"
StatisticalAnalyzer: "I compute statistics"
SpectrumPlotter: "I create plots"
ResultsExporter: "I save results to files"

New collaborators can immediately understand what each piece does.

Red Flags That You Need SRP

Methods longer than 50 lines
Changing one thing breaks another
Can't write a test without mocking 5 dependencies
Classes or functions with 'and' in their description
You can't reuse a piece without bringing the whole system along
The same code is repeated in multiple places with slight variations
You're afraid to refactor

Common Mistakes: Over-Engineering

The most common mistake I see is going too far. You don't need a separate class for every single function. Here's my rule of thumb:

When to create a new class:

The responsibility is complex enough to warrant multiple methods
You might want to swap implementations (different file formats, algorithms)
The code could be reused in different contexts
Testing would be easier with isolation

When to keep it as a simple function:

It's a simple calculation or transformation
It's only used in one place
It has no internal state to manage
It's obvious what it does

For example, computing a simple average doesn't need its own class—just use np.mean(). But if you're computing a suite of related statistics, a StatisticalAnalyzer makes sense.

Performance Notes

You might worry about the overhead of creating multiple objects. In practice, this is negligible for typical scientific workflows. The real performance bottleneck is your algorithms (peak finding, smoothing), not object instantiation.

Your Turn

Right now, open your largest script and identify the top two responsibilities that cause the most pain—usually file I/O or visualization. Extract each into a function or small class. You've just started applying SRP.

Next week, we'll tackle the Open/Closed Principle: how to add new analysis methods without touching (and potentially breaking) your validated code.

Wrestling with monolithic scientific code? Share your experiences in the comments!

Martin, Robert C., Agile Software Development: Principles, Patterns, and Practices (paid link). Pearson Education, 2003. ↩
Martin, Robert C., "The Single Responsibility Principle". The Clean Code Blog, 8 May 2014. ↩

SOLID Principles for Scientists and Engineers: Making Research Code Maintainable

Rob Johnston — Mon, 29 Dec 2025 14:00:00 +0000

Your Research Code Deserves Better (But Not Too Much Better)

It starts innocently enough. You write a 200-line Python script to analyze some experimental data. It works perfectly. Your advisor is happy. You move on to the next experiment.

Six months later, that script is 2,000 lines. You've added three different analysis methods, support for four instrument types, and a plotting system that "mostly works." Every time you add a feature, something else breaks. The only person who understands the code is you—and even you're not entirely sure anymore.

You know the code needs restructuring, but where do you start? You may have heard of "design patterns" and "software architecture," but those resources seem written for people building web applications and enterprise systems, not analyzing spectroscopy data or controlling lab equipment.

This blog series is for you.

What This Series Covers

Over the next few weeks, I'll be publishing a 5-part series on SOLID principles—a set of design principles that help make code more maintainable, testable, and extensible. But instead of the usual enterprise examples, every post uses real scientific scenarios.

Each principle gets its own detailed post with complete, runnable code examples:

Single Responsibility Principle - "One Class, One Job"
Open/Closed Principle - "Extending Without Breaking"
Liskov Substitution Principle - "Interchangeable Components"
Interface Segregation Principle - "Lean Interfaces"
Dependency Inversion Principle - "Depend on Abstractions"

What Makes This Series Different

Real scientific examples. No shopping carts, no user authentication, no enterprise business logic. Just real problems that scientists and engineers face: handling data from different instruments, swapping analysis methods, working with various file formats.

Acknowledges when NOT to apply these principles. Your exploratory Jupyter notebook is fine as-is! Over-engineering is real, and I'll tell you when simple is better.

Complete code examples. Every post includes full, working Python code you can run and modify. Before/after comparisons show what changes and why.

Focus on evolution, not perfection. Most research code starts as a quick script. I'll show you how to recognize when it needs more structure, and how to refactor incrementally without rewriting everything.

Who This Series Is For

PhD students maintaining research code that's outgrown its original scope
Research scientists whose "temporary" script is now supporting three other lab members
Engineers who dread opening their own six-month-old code
Lab managers maintaining code written by departed students

You don't need a computer science degree. You don't need to know what a "factory pattern" is. You just need to write code that's becoming harder to maintain.

The Key Insight

Here's what I've learned after years of writing and maintaining code:

Start simple. Refactor when pain appears.

Your exploratory script doesn't need elegant architecture. But when that script becomes a production pipeline that runs every day for two years, the lack of structure becomes painful. The trick is recognizing when you've crossed that threshold and knowing what to do about it.

That's what this series teaches.

A Preview: The Spectrum of Scientific Code

Not all code needs the same level of design rigour. Your quick data exploration? Keep it simple. That analysis pipeline your entire research group depends on? Time for structure.

Exploratory code → One-off Script → Production Pipeline → Reusable Library
     │                  │                │                     │
No SOLID needed    Light SOLID      Moderate SOLID        High SOLID

What to Expect

Each post is approximately 15-20 minutes of reading time and includes:

A relatable problem that scientists actually face
Complete "before" code showing the issue
Complete "after" code showing the solution
Explanation of why the refactoring helps
Guidance on when to apply (and when to skip) the principle

Posts will be published weekly starting next Monday. Bookmark this page and check back regularly.

Why I'm Writing This

I've spent years writing software, from quick analysis scripts to production pipelines to open-source libraries. I've made every mistake in this series (multiple times). I've written 5,000-line files that even I didn't want to touch. I've broken validated code by adding "just one small feature." I've forced implementations to inherit methods they couldn't possibly support.

I learned SOLID principles the hard way: by feeling the pain of their absence.

This series is the guide I wish I'd had when I started. It's specifically designed for scientists and engineers who need to write maintainable code but weren't trained in software design.

Ready to Dive In?

The first post—Single Responsibility Principle for Scientists and Engineers—goes live next Monday. It covers the most common issue I see in scientific code: classes and functions that try to do too much.

We'll take a realistic spectroscopy analysis script and refactor it step by step, showing exactly how to break apart monolithic code into focused, maintainable pieces.

Until then, take a look at your current code and ask yourself:

When I need to change how I load data, do I have to edit the same file that does the analysis?
When I add a new feature, do unrelated things break?
Have I ever swapped one component for another and gotten strange results?
Do I have classes implementing methods that just raise NotImplementedError?
Can I test my code without connecting to real hardware or reading real files?

If you answered "yes" to any of these, the following posts will show you exactly what to do about it.

Questions or topics you'd like covered? Leave a comment below!

Organizing Source Code for Scientific Programmers: Let's Start a Conversation

Rob Johnston — Mon, 22 Dec 2025 14:00:00 +0000

If you've ever opened a scientific code repository and found yourself lost in a maze of analysis files, scripts, data, and outputs all jumbled together, you're not alone. While line-of-business developers have established conventions (like David Fowler's .NET project structure), scientific computing has its own unique needs that require a different approach.

Scientific code repositories face challenges that traditional software projects don't: managing raw and processed data, organizing interactive analyses alongside automated scripts, handling computational experiments, and ensuring reproducibility across different computing environments and languages.

This post proposes a starting point for discussion. I'd love to hear from the community: How do you organize your scientific codebases? What works? What doesn't? What am I missing?

Why Organization Matters in Scientific Computing

Poor organization doesn't just create inconvenience—it creates real problems. Lost data, irreproducible analyses, and hours wasted searching for files are common consequences. A well-organized repository accelerates science, facilitates collaboration, and makes your research reproducible.

When everyone on your team can predict where files should be, collaboration becomes intuitive rather than frustrating. But what's the right structure?

The Fundamental Principle: Separate by Type and Purpose

The key organizing principle for scientific repositories is to structure by file type and purpose. This creates consistency across projects and makes it intuitive to find what you need. Here's a proposed structure:

project-name/
├── data/
│   ├── raw/
│   └── processed/
├── src/
│   ├── data_processing/
│   ├── analysis/
│   └── visualization/
├── notebooks/
├── scripts/
├── results/
│   ├── figures/
│   └── output/
├── docs/
├── tests/
├── environment/
├── README.md
├── LICENSE
└── .gitignore

Let's break down each component and when to use it. But remember: this is a starting point for discussion, not a rigid prescription.

Core Directories

`data/` - The Sacred Ground

Your data directory should have two subdirectories:

data/raw/: Original, unmodified data files. Treat this as immutable. Never, ever modify files here. You can even set these files as read-only to prevent accidents.
data/processed/: Cleaned, transformed, or analyzed versions of your data.

This separation is crucial for reproducibility. Anyone should be able to run your processing code on the raw data and regenerate your processed data.

Important note: For large datasets, you may want to store only metadata or download scripts in version control rather than the actual data files. Consider using services like OSF, Zenodo, or institutional repositories for large data files.

Question for the community: Do you organize data differently? How do you handle intermediate processing stages? Do you have a data/interim/ directory?

`src/` - Your Core Analysis Code

This is where reusable, production-quality code lives. Think of this as the "scientific guts" of your project. Code here should be:

Organized into logical modules or packages
Well-documented
Testable and (ideally) tested
Importable from interactive environments or scripts

Question for the community: How do you organize multi-language projects? Do you have separate directories for different languages, or do you mix them in src/?

`notebooks/` - Exploration and Prototyping

Interactive environments (Jupyter notebooks, R Markdown, Pluto.jl notebooks, MATLAB Live Scripts, Mathematica notebooks) are fantastic for exploration, but they come with challenges: they can encourage non-modular code, become difficult to test, and tend to accumulate cruft over time.

Best practices:

Use interactive environments for exploration, visualization, and prototyping
Keep them focused on specific questions or analyses
Name them clearly with numbers for ordering: 01-data-exploration.ipynb, 02-initial-modeling.Rmd, 03-sensitivity-analysis.jl
Transition mature code to the src/ directory
Import functions from src/ rather than copying code between notebooks

When an interactive session starts to feel unwieldy, extract the reusable parts into modules in src/.

Question for the community: Some researchers prefer to keep all work in notebooks/scripts. Others prefer to move everything to modules. What's your philosophy? Does it depend on the project stage?

`scripts/` - Automation and Batch Processing

Scripts are for automated, reproducible workflows. These files:

Run without interaction
Accept command-line arguments or configuration files
Can be executed on computing clusters or in pipelines
Orchestrate complete analyses from start to finish

Example use cases:

Data download and preprocessing pipelines
Running models with different parameters
Generating all figures for a paper
Batch processing multiple datasets

A controller script (e.g., run_all.sh, Makefile, Snakefile) that executes the entire analysis workflow in order is extremely valuable for reproducibility.

Question for the community: Do you use workflow managers (Make, Snakemake, Nextflow, Drake, Luigi)? How do you organize pipeline definitions?

`results/` - Analysis Outputs

Store generated outputs here, not in version control (add to .gitignore):

results/
├── figures/        # Plots, visualizations
├── output/         # Tables, statistics, processed results
└── models/         # Trained models, fitted parameters

Why separate from data? Results are generated by code and should be reproducible. If you lose them, you can regenerate them. Data (especially raw data) cannot be regenerated.

Question for the community: Do you version control any results? How do you handle results that take days/weeks to generate?

`docs/` - Documentation

Include:

Project documentation
Analysis notes or lab notebook entries
Manuscript drafts
Supplementary materials
API documentation (if auto-generated)

Question for the community: Where do you keep your manuscript? In the repo? In a separate repo? In Overleaf or Google Docs?

`tests/` - Test Code

Yes, even scientific code should have tests! At minimum, include:

Unit tests for core functions
Integration tests for workflows
Validation tests that check against known results

Testing helps ensure correctness and catches bugs when you modify code.

Question for the community: What's your testing philosophy for scientific code? Do you test everything, just critical functions, or not at all?

Essential Files in the Root

README.md

Your README is the front door to your project. It should include:

Project overview and goals
Installation instructions
Quick start guide
Project structure explanation
How to reproduce key results
Dependencies and requirements
Citation information
Contact information

Environment Management

Include files that specify your computational environment. The specifics depend on your language and tools:

Python:

environment.yml (for conda)
requirements.txt (for pip)
pyproject.toml (for modern Python packaging)

renv.lock (for renv)
DESCRIPTION (for R packages)
install.R (installation script)

Julia:

Project.toml and Manifest.toml

MATLAB:

Dependency list in README or separate documentation

Multi-language projects:

Dockerfile (for containerized environments)
Separate environment files for each language
Shell script that sets up entire environment

Question for the community: How do you handle dependencies that span multiple languages? Do you use containers? Virtual machines? Detailed documentation?

LICENSE

If your project is open source, include a license. Common choices for scientific code include MIT, BSD, or GPL licenses.

.gitignore

Prevent clutter by ignoring generated files. Language-specific examples can be found at https://github.com/github/gitignore/tree/main.

All projects:

data/raw/*
results/*
.DS_Store (for the macOS operating system)

Organizing for Different Project Scales

Small Projects (Single Analysis → Single Paper)

For small projects, a simplified structure works well:

project/
├── data/
├── analysis/
├── results/
├── environment/
└── README.md

This is fine for exploratory work or class projects where you don't expect significant expansion.

Large Projects (Multiple Studies, Multiple Papers)

For field studies, multi-year projects, or projects with multiple outputs:

project/
├── data/
│   ├── study1/
│   ├── study2/
│   └── shared/
├── src/
│   ├── preprocessing/
│   ├── analysis_core/
│   └── utils/
├── analyses/
│   ├── paper1/
│   ├── paper2/
│   └── exploratory/
├── docs/
└── manuscripts/
    ├── paper1/
    └── paper2/

The key is organizing analyses by the output (paper, report) they support while keeping shared code in a central src/ directory.

Question for the community: How do you organize multi-year, multi-paper projects? One repo or many? How do you handle shared code?

Self-Contained Projects

Strive for self-containedness: everything needed to reproduce your analysis should be in the project directory. This sometimes conflicts with avoiding duplication (e.g., when multiple projects share data), but for publishable research, self-containedness usually wins.

A colleague should be able to:

Clone your repository
Set up the environment
Run your analysis scripts
Reproduce your results

Question for the community: How do you balance self-containedness with sharing code/data between projects?

Version Control Best Practices

What to Track

All code (scripts, interactive analyses, source files)
Documentation
Environment specifications
Small data files (< 100MB)
Metadata about large data files

What NOT to Track

Large data files (use data repositories instead)
Generated results and figures
Temporary files
Language-specific artifacts (compiled binaries, caches)
IDE-specific settings (unless shared intentionally)

Commit Messages

Good commit messages should describe what changed scientifically, not just what changed in the code:

❌ "Updated analysis"

✅ "Added bootstrap confidence intervals to treatment effect estimates"

Question for the community: Do you have commit message conventions for scientific projects?

Common Pitfalls and Solutions

Pitfall 1: The Analysis File Sprawl

Problem: 50 files with names like "Untitled1", "Copy of Final_Analysis_v3"

Solution:

Name files descriptively with numbered prefixes
Regularly archive or delete obsolete files
Transition stable code to modules

Pitfall 2: Data Soup

Problem: Raw data, processed data, results all mixed together

Solution:

Strict separation of raw/processed/results
Document data provenance
Use metadata files to track processing steps

Pitfall 3: Hardcoded Paths

Problem: Absolute paths that only work on one person's computer

Solution:

Use relative paths from the project root
Use path manipulation libraries (pathlib in Python, file.path in R, etc.)
Consider configuration files for environment-specific settings

Pitfall 4: Missing Dependencies

Problem: "It works on my machine" but fails everywhere else

Solution:

Maintain updated environment specifications
Document system dependencies
Consider using containers (Docker, Singularity) for complex environments

Question for the community: What other pitfalls do you encounter? What solutions work for you?

Making This Real: A Call for Examples

Theory is great, but examples are better. I'd love to see:

Links to well-organized public scientific repositories
Templates or cookiecutter projects for different fields
Adaptations of this structure for specific use cases
Counter-arguments: When does this structure NOT work?

Conclusion: The Conversation Starts Here

Good code organization isn't about following rules dogmatically—it's about making your life easier and your science better. The structure I've proposed here is a starting point, not a final answer.

Core principles that seem universal:

Separate concerns: Data, code, and results in different directories
Preserve raw data: Never modify original data files
Make code modular: Extract reusable functionality
Document everything: Future you will thank present you
Use version control: Track changes and enable collaboration
Enable reproduction: Someone else should be able to reproduce your work

But the implementation of these principles will vary based on:

Your programming language(s)
Your field's conventions
Your team's preferences
Your project's scale and complexity
Your computing environment (laptop, HPC cluster, cloud)

Your Turn: Join the Discussion

I'd love to hear from you:

What works? How do you organize your scientific code? What's your directory structure?
What doesn't work? What have you tried that failed? What pain points remain?
What's missing? What essential aspects of scientific code organization did I overlook?
Language-specific tips? What works particularly well in your language of choice?
Field-specific conventions? What are the norms in your discipline?

Please share your experiences in the comments. Let's build a community knowledge base of what actually works in practice.

Further Resources

"Good Enough Practices in Scientific Computing" by Wilson et al.¹ - Comprehensive guide to scientific computing practices

Software Carpentry - Workshops on version control, testing, and project organization²

"Ten Simple Rules" series in PLOS Computational Biology³ - Including rules for taking advantage of Git and GitHub

Cookie Cutter Data Science - A standardized project structure template⁴

The Turing Way - Handbook for reproducible, ethical, and collaborative data science⁵

Remember: the goal isn't perfection, it's progress. Start organizing better today, and iterate as you learn what works for you and your team.

What's your approach to organizing scientific code? Share your structure, tips, or questions in the comments below!

Wilson G, Bryan J, Cranston K, Kitzes J, Nederbragt L, Teal TK (2017) Good enough practices in scientific computing. PLOS Computational Biology 13(6): e1005510. https://doi.org/10.1371/journal.pcbi.1005510 ↩
Software Carpentry. "Lessons." https://software-carpentry.org/lessons/ ↩
Perez-Riverol Y, Gatto L, Wang R, Sachsenberg T, Uszkoreit J, Leprevost FdV, et al. (2016) Ten Simple Rules for Taking Advantage of Git and GitHub. PLOS Computational Biology 12(7): e1004947. https://doi.org/10.1371/journal.pcbi.1004947 ↩
DrivenData. "Cookiecutter Data Science." https://cookiecutter-data-science.drivendata.org/ ↩
The Turing Way Community. (2022). The Turing Way: A handbook for reproducible, ethical and collaborative research. Zenodo. https://doi.org/10.5281/zenodo.3233853 ↩

My First Blog Post - A Journey in Programming for Scientists and Engineers

Rob Johnston — Sat, 06 Dec 2025 21:32:17 +0000

Welcome to My New Blog

I've been thinking about starting a blog for a while now, and as we approach the new year, it feels like the perfect time to finally take the plunge. So here we are—my very first blog post.

What This Blog Is About

This space will be dedicated to scientific programming, a field that sits at the fascinating intersection of software engineering and scientific computing. Whether you're writing code to analyze experimental data, simulate complex systems, or build tools for research, the quality of your code matters just as much as the science behind it.

I plan to explore topics that help us write better, more maintainable scientific software. Some areas I'm particularly excited to dive into include:

SOLID Principles: These five principles of object-oriented design can transform how we structure scientific code, making it more flexible and easier to test.
Design Patterns: The Gang of Four patterns offer elegant solutions to common programming problems, and I want to explore how they apply specifically to scientific computing contexts.
Testing Scientific Code: From unit tests to validation against known results, I'll explore strategies for ensuring your computational work is correct and remains correct as your code evolves.

Why Scientific Programming Needs Better Software Engineering

Too often, scientific code is written once, runs once, and then becomes a mystery even to its original author. We've all encountered those 2000-line scripts with variable names like temp2 and comments that say "this works, don't touch it." But as computational work becomes central to modern science, we need to approach our code with the same rigour we apply to our experiments.

What's Coming

In the posts ahead, I'll be sharing practical insights, code examples, and lessons learned from applying software engineering principles to real scientific problems. My goal is to make these concepts accessible and immediately useful, whether you're a researcher who codes or a developer working on scientific applications.

Thank you for joining me at the start of this journey. I'm looking forward to exploring these topics together and learning from the conversations that follow.

Here's to writing better code in the new year!

Stay tuned for my next post, where I'll dive into the first of the SOLID principles and why it matters for scientific code.