<img src="https://secure.leadforensics.com/794635.png" style="display:none;">
Skip to content
CS_logo_navy
  • Product
    • Product and features
      • Code quality
      • Team dynamics
      • Software delivery
      • Code Coverage
      • Integrations
      • AI Coding
  • Resources
    • Gartner® report
    • Resource Hub
      • Thought Leadership blog
      • Customer cases
      • CS Academy
      • Tutorials
      • Use cases
      • Research
      • FAQs
      • Docs site
    • Support Hub
  • Pricing
  • Company
    • Company
      • Partners
      • Careers
      • Privacy & security
    • Contact Us
  • For Developers
    • Developer Hub
      • IDE extension
      • AI Coding
      • Tutorials for developers
      • Engineering Blog
Try for free Login
Published at October 27, 2023

Visualize Conway's Law in your Codebase

Conway's Law is an important principle. How can we ensure that our dev teams are on track with an architecture that supports the way we are organized?

Development Teams visualized with CodeScene's Teams Maps

Back in 2014, I claimed that the "intersection between people and code is an often overlooked aspect of software development. When there’s a misalignment between how you’re organized versus the work style your software architecture supports, code quality and communication suffers." (Your Code as a Crime Scene). We've all seen it happen, and it's painful.

 

Fortunately, and thanks to the great work of Matthew Skelton & Manuel Pais of Team Topologies fame, there has been a growing interest in organizational design. Team Topologies presents a valuable contrast to the traditional static view of an organization. Instead, the authors state that we need a dynamic model "that takes into consideration how teams grow and interact with each other". More specifically, Team Topologies uses Conway's Law as one driver for team design. That is, the modularity of a software design needs to align with the responsibilities of the development teams.

 

Conway's Law is an important principle. So how can we ensure that we are on track and that we -- as development teams -- have an architecture that supports the way we are organized? Are we working with or against our software architecture? Follow along, and I'll take you through a new way to visualize both Conway's Law and development teams.

 


Modularity alone doesn't guarantee a successful architecture

One of the great tragedies of software design is that we -- the people who build the system -- are invisible in the code itself. Consequently, we tend to underestimate the impact of a misaligned software architecture: ever experienced frequent merge conflicts, long lead times for features, and a calendar that looks like a chessboard of sync meetings? Chances are that the teams aren't super well aligned with the code.

 

It's a massive challenge, and that's why I'm so happy to see CodeScene's new improved visualizations: by hovering over a team name, I immediately see that team's operational areas in the code:

 

Teams_View_CodeScene e

 

Of course, that's only the starting point. We'll dive deeper soon, but let's first explore what to look for in these visualizations.

 
 

Reverse engineer team dynamics from code

A successful software organization has two key properties:

  1. Team cohesion means that the team carries a meaning from an architectural perspective; the members of a team work on related parts of the code.
  2. Team coupling: loosely coupled teams minimize coordination and the risk of conflicting changes to the code, whereas tight dependencies between different teams become coordination bottlenecks.

Both are important. A cohesive team makes coordination and communication so much easier since all members work on related aspects of the software. They share the same context. And loose dependencies to other teams bring increased autonomy, fewer reasons to sync, and less unpleasant deployment surprises in general.

A codebase under active development is a moving target, so we wanted to be able to auto-generate a visualization that shows how well we do on these two dimensions. Hence we turned to one of the most under-utilized social data sources that we have within software development: our version-control repositories. We decided to reverse engineer the team structure from the evolution of the code.

For team cohesion, we do this by analysing the overlap between the team member’s commits and the files in the codebase. Following the same principle, we can also discover overlaps in commits to the same parts of the code by members of different teams, which would indicate coupling. Let's see what it looks like:

team-code-alignment

The interactive view visualizes dependencies between teams and developers in a codebase. Each shape is a team, each circle represents a specific developer in that team. Visualization from the CodeScene tool.

In the preceding figure, we see that 3 teams seem strong on cohesion. However, the team in the upper left corner -- indicated by its red fill -- clearly lacks cohesion: the data suggests that it's more a group of individuals with an artificial team boundary around them than a team that carries meaning from an architectural perspective.

Of course, this data isn't supposed to stand on its own. Rather, it's input that you use to make decisions around team responsibilities, scopes, and architectural boundaries. Let's look at the common patterns you might come across.

 

Violating coupling and cohesion: explore the root causes

There are multiple root causes for poor team-code alignment. Some of the most common are:

  • Unclear ownership: Parts of your architecture might lack team ownership and, consequently, become coordination magnets You often recognise these packages via their names; common, misc, and services are the usual suspects. The CodeScene visualizations let you highlight these areas of tight team coupling too:

    Coordination Needs Map - CodeScene
  • Lack of team focus: This happens when members of a team work in parallel on disparate domains or aspects of the system. Coordination and communication work best when there’s a shared purpose and clear goals. Streamlining the tasks for a team helps. Often, achieving that focus implies restricting the amount of work in progress.
  • Architectural decay: Many organizational problems are caused by technical issues.  There will never be a fit between the teams and the code if the design itself suffers strong dependencies or lack of cohesion. Interestingly enough, many team coordination issues can be resolved by architectural improvements and code refactoring. Yes, it's harder to refactor than to move boxes on an org chart, but necessary nonetheless.

While you cannot deduce these root causes from the team-code visualizations themselves, other CodeScene analyses let you drill down and identify areas of improvements:

  • Hotspots and Change Coupling let you discover complex dependencies and code quality issues in the system. Check out the examples in the Managing technical debt article.
  • Coordination and parallel development analyses highlight where in the code authors from multiple teams need to coordinate their code changes. Check out the Measure Conway's Law article for examples and tips.



Shine a light on the organizational web

In the book Reinventing Organizations, Frederic Laloux observes that every organization's real structure looks like a web; a "web of fluid relationships and commitments that people engage in to get their work done". A software organization is of course no exception.

The team-code alignment analysis brings visibility into this web by illustrating the dynamic team aspects of building software. Ultimately, it's about helping us all in making sure that our actual organization -- as seen from the code -- matches our desired organization.

At CodeScene we use the team-code alignment feature internally and the insights we gain from it are very valuable. Insights that we couldn't have gotten otherwise. Why not take it for a test drive? Your teams are worth it.

Adam Tornhill

Adam Tornhill

Adam Tornhill is a programmer who combines degrees in engineering and psychology. He’s the founder and CTO of CodeScene where he designs tools for code analysis. Adam is also a recognized international speaker and the author of multiple technical books, including the best selling Your Code as a Crime Scene and Software Design X-Rays. Adam’s other interests include modern history, music, retro computing, and martial arts.

Twitter Author Linkedin Author Website Author
Elements Image

Subscribe to our newsletter

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Semper neque enim rhoncus vestibulum at maecenas. Ut sociis dignissim.

Get Started

Latest Articles

Use Guardrails for AI-Assisted Coding
AI Coding

Use Guardrails for AI-Assisted Coding

AI-assisted coding is still in its early stages. This article explores the immediate and future impacts of integrating AI assistants into t...

AI Coding Guardrails CodeScene
Adam Tornhill
AI vs. Code Maintainability: Extending Cursor with Automated Code Reviews
AI Coding

AI vs. Code Maintainability: Extending Cursor with Automated Code Reviews

How to integrate automated code reviews within Cursor AI for maintainable, high-quality code with real-time feedback and AI-refactoring.

AI vs. Code Maintainability: Extending Cursor with Automated Code Reviews
Adam Tornhill
Your Team’s Automated Defense Against Technical Debt
Technical Debt

Your Team’s Automated Defense Against Technical Debt

Discover our new Context-Aware Gating feature for pull requests. Automate Code Health reviews to ensure quality standards and improve maint...

Your Team’s Automated Defense Against Technical Debt
CodeScene Team
codescene-logo-dark

Next generation code analysis

StaticCodeAnalysis_HighPerformer_HighPerformer StaticCodeAnalysis_HighPerformer_Mid-Market_HighPerformer-1 StaticCodeAnalysis_MomentumLeader_Leader-1

 

Home

Pricing

Try for free

Talk to sales

Request a demo

Product

Code quality

Team dynamics

Software delivery

Code Coverage

Integrations

AI Coding

Resources

Thought leadership blog

Tutorials

Use cases

Whitepapers

FAQs


For developers

Developer hub

IDE extension

Engineering blog

AI Coding

Tutorials for developers

Company

Partners

Careers

Privacy and security

 

Support Hub

Visit linkedin Visit youtube
Copyright 2025 © CodeScene AB