Skip to main content
What you’ll learn in this lesson:
  • Apply the Principle of Least Complexity to keep models maintainable
  • Make calculations explicit and self-documenting
  • Ensure every output is traceable back to source data
  • Reuse components to reduce duplication and errors
You’ve built a working project through Modules 1-5. Now it’s time to make it production-ready: not just functional, but maintainable, auditable, and clear to anyone who inherits it. This lesson introduces four design principles that separate good models from great ones.

​
The four principles

1. Least Complexity

Keep models as simple as the methodology allows.Don’t add calculation steps that the methodology doesn’t require. Don’t optimize prematurely. A simple model that’s correct is worth more than a clever model that’s hard to verify.

2. Explicit Over Implicit

Clear, documented logic beats clever shortcuts.Every unit conversion, every factor application, every conditional branch should be a visible node in the model, not hidden inside a complex Keisan expression.

3. Audit Trail Everything

Traceability from credit to source event.Every output value should be traceable backwards through the model tree to the specific events and evidence that produced it. Verifiers will follow this trail.

4. Don't Repeat Yourself

Reusable components and calculations.If two batch types use the same emission factor calculation, build it once and reference it. Duplication creates drift: when one copy is updated, the other becomes wrong.

​
Principle 1: Least Complexity

In practice:
  • Map each model step to a specific equation in the methodology document
  • If a calculation step doesn’t correspond to a methodology requirement, question whether it’s needed
  • Avoid “future-proofing”: add complexity only when the methodology demands it
  • Prefer fewer, well-understood nodes over many granular sub-calculations
Least complexity doesn’t mean least steps. Breaking a formula into intermediate nodes (as you did in Module 2) is good design: it adds clarity without adding unnecessary logic. The principle is about not adding logic the methodology doesn’t require.

​
Principle 2: Explicit Over Implicit

Every transformation should be visible in the model:
A single Keisan expression that does everything:
This is hard to audit, hard to debug, and impossible to verify intermediate values.
Name every intermediate node descriptively. A node called dry_feedstock_mass_tonnes tells a verifier exactly what it is. A node called calc_step_2 tells them nothing.

​
Principle 3: Audit Trail Everything

Verifiers trace the chain: credit → report → batch → model calculation → event → evidence. Every link in this chain must be unbroken.
1

Output → Calculation

Every batch output datapoint should trace to a specific model output node.
2

Calculation → Input

Every model node should trace to specific datapoint slugs from event types or static inputs.
3

Input → Event

Every datapoint value should trace to a specific event instance with a date, source, and tracking ID.
4

Event → Evidence

Every event should have associated evidencedocuments, files, or URLs that support the reported values.
A broken audit trail is a verification failure. If a verifier asks “where did this 29.36 tCO2e come from?” and you can’t trace it back to a delivery ticket and weighbridge slip, the batch won’t pass verification.

​
Principle 4: Don’t Repeat Yourself

The same emission factor (0.417 kg CO2e/kWh) hardcoded as a constant in three different models. When the grid factor updates, you need to find and change all three.
Other reuse patterns:
  • Use static inputs for all factors that might change (emission factors, conversion ratios, methodology parameters)
  • If multiple batch types need the same calculation, consider whether a single model can serve both
  • Keep the number of event types minimal: only add new ones when the data genuinely comes from a different source

​
Check your understanding

Keep models as simple as the methodology allows. Every calculation step should correspond to a requirement in the methodology. Don’t add unnecessary logic, premature optimization, or “future-proofing.” Note: breaking formulas into intermediate steps for clarity is NOT unnecessary complexity. It aids verification. The principle targets unnecessary logic, not necessary steps.
Verifiers need to check intermediate values at each step of the calculation. If everything is packed into one complex expression, they can’t verify the parts, only the final result. Explicit intermediate nodes let verifiers confirm that dry mass is correct, then that carbon content is correct, then that the CO2 conversion is correct, building confidence at each step.
Next, explore advanced techniques for complex projects in Lesson 6.2: Advanced Techniques.