Developing Useful Applications (Part 1) Breaking It Down

Table of Contents

1. Breaking It Down(this part)
• Introduction
• Managing Complexity
• Intent vs Implementation
• Further Information
2. Persistence (Part 2)
• The Challenges of Persistent Information
• Source Code and Software Assets Are Data Too
• Software Entropy and Long-Term Maintainability
• Project Management Generates Persistent Data
• Garbage In, Garbage Out: When Bad Data Distorts Decisions
• Conclusion: Treat All Project Information as an Asset
• Further Information
3. Frequently Forgotten Factors (Part 3)
• UX & DX
• Networks
• Third Parties

ntroduction

There’s a world of difference between a demo app you knock together in an afternoon and a production-grade system that delivers value over time.   

Real applications must deal with:

• Complexity
• Persistence
• User Experience (UX)
• Developer Experience (DX)
• Network Communication
• Third Parties

Managing Complexity

Breaking It Down

To deal with complexity effectively:

• Separate Intent, Concepts, and Implementation
• Decompose functionality into modules, types, and functions.
• Use concepts, guarantees, and encapsulation to reason about parts in isolation.
• Keep your implementation aligned with the concepts it's supposed to represent.
• And keep your concepts aligned with what the system is supposed to do.

Misalignment between intent, concepts, and implementation creates friction.

>

Intent vs Implementation

Why Separate Intent, Concepts, and Implementation?

They are differentiated by

• Impact on complexity
• Expressiveness
• Impact on costs
• Speed of change
• Utilisation over the development/product lifecycle.

Because

• Intent is constrained by user needs and stakeholder politics.
• Implementation is constrained by technology, time, and budget.
• Intent evolves slowly. Implementation changes constantly.
• High-level concepts reduce cognitive load and communicate goals and benefits, clarify intent and encapsulate technical detail.
• Low-level concepts structure and organise the implementation.  

Relationship with Costs and Benefits

Real-world software has both functional (value-generating) and non-functional (cost-related) requirements.  

• Intent describes why the system exists (the benefits) and the goals it is trying to achieve.
• Concepts describe what the system is made of (the mental models) and give us a language to reason about Intent and Implementation
• Implementation describes how it works (the technical details) and determines the costs in resources.   

Cost Trade Offs in Implementation

How an application is implemented is an exercise in juggling resource use such as

• Memory
• Performance
• Developer Effort
• Usability

Reducing one cost may increase another.

Speed of Change

Intent tends to change slowly—often painfully so. That’s because:

• Improvements in benefits need to be sought out and chased with customer research, focus groups and feedback from beta testers.
• Everyone has an opinion on what “value” means.
• Aligning stakeholders takes time.
• Introducing a new benefit usually means negotiating a new compromise.

Implementation changes quickly. That’s because:

• Improvements in costs come knocking at the development team's door as tools improve, libraries mature, and developers gain experience.
• Everyone loves it when “costs” go down. 
• There are fewer delays because of co-ordination and communication costs as everyone is on the same page.

As time goes on, the team: 

• Understands the domain better.
• Learns the codebase and its quirks.
• Gets better at using the platform and tools.
• Sees more opportunities for improvement.

Frameworks evolve. Languages adopt better abstractions. Tools reduce boilerplate and automate the boring parts. All of these shift the implementation landscape, making things that were once hard, easy—and giving you reasons to change how things are built. 

The Source of the Concepts

A key idea in Domain-Driven Design is ubiquitous language: shared concepts and terminology built collaboratively with stakeholders.

Over time, a team builds a refined, shared vocabulary—one that captures both problem-domain ideas and the corresponding solution space. These concepts live in:

• Conversations with subject matter experts
• Tooling and platforms used
• Reusable components and internal libraries

Good concepts help reduce complexity and improve communication.

Development and Product Lifecycle

Most Software Development Life Cycle (SDLC) models include:

• Planning – Define goals, scope, and requirements
• Analysis – Gather and clarify needs using domain knowledge
• Design – Create structure and architecture
• Implementation – Build the system
• Testing – Validate functionality and correctness
• Deployment – Ship to users
• Maintenance – Ongoing updates, fixes, and improvements

Each stage benefits from continuous feedback and refinement. Ubiquitous language plays a crucial role throughout, especially during analysis, prototyping, and maintenance. Never underestimate people's ability to mis-communicate.

At some stages Intent will be the focus in others Implementation.

A Practical Break down

I like to break down the Design and Implementation phases into

1. Make It Work in Principle
   • Spike or proof-of-concept
   • Explore feasibility, intent, and high-level trade-offs
2. Make It Work in Practice
   • Build a Minimum Viable Product (MVP)
   • Balance implementation detail with early feedback
3. Make It Easy to Use (UX)
   • Reduce cost and effort for users
   • Design for mistakes, exploration and experimentation:
     • Use poka-yoke (mistake-proofing)
     • Support undo/reversal
     • Provide clear, actionable warnings
     • Avoid alert fatigue
4. Make It Easy to Maintain (DX)
   • Reduce cost and cognitive load for developers
   • Design for mistakess,, exploration and experimentation:
     • Use unit tests for fast feedback
     • Favor simple code paths
     • Use sensible defaults
     • Build reusable components
     • Apply restrictions and constraints intentionally

At each step: test, get feedback, iterate.

Decomposing Functionality: It’s not just breaking things apart

Decomposing functionality is one of those deceptively simple ideas.

Reductionism is a common strategy to deal with complexity, it's a cornerstone of science for example, so breaking big things into smaller things is an obvious approach. However, if components are separated at the boundaries of weak vague concepts, or the boundaries themselves are ill-defined, then complexity will worsen instead of improve.

Naming: Where concepts meet clarity

• Clear, expressive names reflect clean, well-bounded concepts.
• Good names improve readability and signal design quality.

If you're reaching for vague names like Manager, Processor, or Helper, it might be worth asking: do I really understand what this thing is doing?

To decompose effectively:

• Boundaries should reflect real concepts, not just “this was getting long.”
• Encapsulation should hide irrelevant details and expose clear responsibilities. 

Coherence and Coupling: Testing as a design tool

Test-First Design (or at least test-soon design) can reveal how well the code is decomposed. If you can tease out a component from your program well enough to test it in isolation, then it is probably nicely self-contained, and you have good encapsulation.

Other signs of good encapsulation are:

• Interfaces hide internal details
• External code doesn’t need to "poke around" internals

Watch out for:

• Excessive chatter between modules
• Leaky abstractions
• Violations of SOLID principles

Concepts, Restrictions, Guarantees and Encapsulation

A human can only hold four pieces of information in working memory at a time. We deal with complexity by grouping things into higher-level concepts. This is called chunking, and it’s the mental compression algorithm that keeps our brains from crashing.

This works beautifully in software if your encapsulations are tight, and your components behave as advertised.

To help with that, use restrictions and guarantees that strengthen your boundaries such as:

• Interfaces and protocols
• Type inference and compiler checks
• IDE validation and annotations (red squiggles)
• Unit tests

These warn you if you are veering off in the wrong direction, and help tighten your encapsulation and define the edges of your concepts.

When Intent, Concept, and Implementation Align

When a component’s name, idea, and behavior match up, the system feels intuitive.

When they drift apart, things fall apart:

• Encapsulation leaks
• Abstractions crumble
• Complexity creeps back in

In short: if a component doesn’t do what its name or interface implies, that’s a problem. Not just for the code, but for anyone trying to understand or maintain it.

Decomposition Done Right

Good decomposition isn't about cutting things up. It's about shaping things that:

• Represent strong concepts
• Fit together cleanly
• Communicate clearly

Strong concepts with meaningful names. Components with encapsulation that reveals intent, and conceals implementation.  

That’s where the real simplicity lives.

Further Information

Related Posts

• Persisting Data, Code and Workflow Tracking
• UX & DX

Articles

• Ubiquitous Language

Books

Domain-Driven Design: Tackling Complexity in the Heart of Software