Architectural Archaeology

There are two ways to read someone else' code and learn the Architecture of the code:


Thinking usually results in finding and fixing a bug in one's own code.

Thinking also works for maintaining code written by someone else, given that the code is already understood.

Using a Debugger

Using a debugger helps to find strange behaviour in alpha-code, caused by typos and design blunders.

Debuggers help with Architectural Archaeology — figuring out how code works.  

Usually, the subject code has been written by someone else, although, one's own code may seem foreign if enough time has passed between writing and reading/understanding the code.

Maintenance Engineering

The first task of Maintenance Engineering is to understand the subject code.

DI - Design Intent

It is the Architect's responsibility to make a design clear and understandable to the reader.


Comments typically become stale and uninformative.

Comments are not automatically tied to the code.  Near the rushed end of a project, the code is changed and automatically compiled, but, comments are not upgraded.

Comments tend to be overlooked because they are not on the critical path of making the software system work.


Ideally, comments should be automatically transpiled into working code.

This is not currently possible, but it is possible to get closer to this goal.

Some comments can be automatically compiled into executing code.  

Statecharts are a specific example.  

I, also, show that it is possible to compile diagrams to code.  IMO diagrams can express DI better than stale comments.

Current PLs express implementation details.  Theorem provers express relationships that apply to the universe of programming.[1]  Currently, there is no PL for expressing the various forms of Software Architecture and Software Engineering.[2]

[1] Expressing relationships about the Universe of Programming is not the same as creating a Programming Language (PLs are reductions of the Universe to simple-to-use subsets - parts of the Universe are elided (hidden, but not ignored)).

[2] Engineering is not coding.  Implementation is coding.  For further discussion, see