05.【FCMD】 When Design Becomes Code, “Diff” Gains Meaning

— The Decisive Difference from GUI CAD

tags: Mechanical Design, CAD, Git, FreeCAD, Python

Introduction

So far in this series, we have seen how to:

Now comes the final and most important question:

Why go this far to write designs as code?

One clear answer is this:

Changes become meaningful “diffs.”

Why Diffs in GUI CAD Are Hard to Interpret

GUI CAD tools do keep history and feature trees.
Yet many designers have experienced situations like these:

The problem with GUI-based workflows is this:

The result remains, but the intent does not.

In Code-Based Design, a Diff Is a Design Change

In code-based design,
a design change appears directly as a text diff.

For example, changing the plate length:

- LEN = 120.0  # mm
+ LEN = 160.0  # mm

With this alone, you immediately know:

Design Decisions Also Become Diffs

Not only dimensions, but design rules themselves
are preserved as diffs.

- if LEN > 100:
-     THK = 8.0
+ if LEN > 150:
+     THK = 10.0

This is nearly impossible to achieve with GUI CAD.

Here, the following are explicitly recorded:

That reasoning remains visible in history.

Design Reviews Become Possible

Once designs are written as code,
design reviews become real using Git.

This transforms design from a manual task into a
manageable, reviewable artifact.

Diff Comparison: GUI CAD vs Code-Based Design

Aspect GUI CAD Code-Based Design
Diff readability Low High
Intent traceability Difficult Explicit
Review method Verbal / screen sharing Git
Rollback Manual Commit revert

Why Handover Becomes Easier

With code-based design,
you are not handing over “how to operate the CAD.”

Instead, you hand over:

Because these remain as code,
future designers can answer the question:

“Why is it designed this way?”

even long after the original work was done.

You Do Not Need to Code Everything

One important clarification:

You do not need to code:

The key principle is this:

Only put into code what you want to preserve as a meaningful diff.

How This Fits in the Series

Article 05 is the answer key
for the entire series.

Conclusion

The greatest value of writing designs as code
is not automation or AI.

It comes down to one thing:

Changes become meaningful, reviewable diffs.

There is no need to reject GUI CAD.
But within a design, the following should be preserved as code:

With that alone,
design becomes a long-term, reusable asset.

Notes

The code shown in this article is provided as an illustrative example
to explain the design methodology.

It is not intended for direct production use or redistribution.

Actual design code and licensing policies are managed here: