Invisible Elefant

by Oleg Sovetnik

When we dive into a legacy project that has been in development for years, with several teams having worked on it, and it seemingly functioning, we often find ourselves in a situation where the backlog priorities shift from “add feature X” to “speed up Y” or “fix Z.” Everyone realizes that something has gone wrong, but there’s no clear way to return to active development and progress. The domain of the project is represented by various artifacts, and the person with all the knowledge has left (“hit by a bus” scenario).

At this point, the project has usually blended both the idea (Domain) and the implementation method, meaning the abstractions have leaked, and what the project represents semantically (Domain complexity) is inseparable from how it is written syntactically (Added complexity). Let’s focus on the first question: what does the project represent semantically?

To address this, we need to analyze the available artifacts and their meaningful content:

1. Code — Even well-structured code often fails to reflect the meaning of the project. When it devolves into “spaghetti code,” it becomes overly detailed and difficult to comprehend. Reading it takes a lot of time, and it only shows how the system works now, without answering why it works that way or how it should work. There’s too much syntax and too little semantics.
2. Git — The commit history records who made changes and when, but it doesn’t explain the meaning or context of those changes.
3. Documentation — It is usually outdated and updated with delays, failing to provide a complete picture of the project’s structure and goals.
4. Task History — This mainly reflects what was planned (which often differs from what was actually done) and tracks errors and failures.

I Didn’t Even Notice the Elephant!

The domain of the project is only represented in partial views, making it difficult to grasp and understand. This can be compared to the parable of the blind sages and the elephant: each person perceives a different part, but no one sees the whole. Developers spend an enormous amount of time reconstructing the project’s meaning, which slows down both development and maintenance.

We need to view the project in a more visual and holistic manner. A mind map could be the solution to this problem. If code can be represented as a tree structure, as can a mind map, then the domain concepts can be arranged in a hierarchy. This visualization would make complex systems easier to grasp and help synchronize understanding between the team and the code.

semantics syntax meaning elephant metaphor