Software Team Sociology: Developing Useful Applications (Part 1) Complexity and Intent vs Implementation

Part 1 (this part)

Introduction
Managing Complexity
Intent vs Implementation

Part 2

Persistence

Part 3

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
Utilitisation 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 teams door as tools improve, libraries mature, and developers gain experience.
Everyone loves it when “costs” go down.
There is less 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 peoples ability to mis-communicate.

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

A Practical Breakdown

I like to breakdown the Design and Implementation phases into

Make It Work in Principle
- Spike or proof-of-concept
- Explore feasibility, intent, and high-level trade-offs
Make It Work in Practice
- Build a Minimum Viable Product (MVP)
- Balance implementation detail with early feedback
Make It Easy to Use (UX)
- Reduce cost and effort for users
- Design for mistakes:
  - Use poka-yoke (mistake-proofing)
  - Support undo/reversal
  - Provide clear, actionable warnings
  - Avoid alert fatigue
Make It Easy to Maintain (DX)
- Reduce cost and cognitive load for developers
- Design for mistakes:
  - 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, its 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.