How to read a code city
Every building is a file, every district a folder. The height and the color of a building each show a metric. Color metrics go from white (low) to red (the highest value in the project).
Change and history
Where does the work happen, and which code keeps coming back?
Change frequency
Number of non-merge commits that changed a file.
Hotspots are where most bugs appear and where refactoring pays off most.
Hotspots
Number of commits multiplied by lines of code of a file.
Hotspots are where most bugs appear and where refactoring pays off most.
Churn and bug fixes
Churn is the sum of lines added and removed over the history. Bug fix commits are commits whose message contains fix, bug, hotfix, defect or regression.
Code that is rewritten a lot and fixed often points to unclear requirements or a fragile design. Bug fixes are only detected by the commit message.
Changes within the last 360 days
Number of commits that changed a file during the last 360 days.
Separates the active parts of the project from stable or abandoned code.
Number of commits
Number of non-merge commits that changed a file, renames are followed.
Shows where development concentrates. Frequently changed files deserve good tests and clear structure.
Code age
Days between the last change of a file and the imported commit. For an older commit the age is measured at that commit, not today.
Old, untouched code is either stable or forgotten. Together with knowledge loss it shows code nobody knows any more.
Change coupling
Number of files that changed together with a file in at least 2 commits and in at least 30 % of its changes. Commits with more than 50 files are ignored.
Shows hidden dependencies the code does not reveal. A change there usually needs changes elsewhere.
Knowledge and people
Who knows the code, and what happens when they leave?
Changes by author
How many commits touched each file and who made them.
Shows at a glance where the work happens and which people carry which parts of the code.
Knowledge loss
Share of the lines of a file (by blame) written by authors without a commit in the last 180 days.
Tall red buildings are a lot of code that hardly anyone in the team still knows. Changes there are slow and risky, good candidates for pairing, documentation or a handover.
Contributor risk
Share of the lines of a file written by its main author.
If that person leaves, the knowledge leaves with them (bus factor). Together with knowledge loss it shows where this is about to happen.
Number of authors
Number of different authors who changed a file, unified by .mailmap.
Many authors spread the knowledge but can mean unclear responsibility. A single author is a contributor risk.
Size and complexity
How big and how hard to understand is the code?
Lines of code
Number of lines of a file.
Large files are harder to understand and to change. Combined with other metrics it shows where problems weigh most.
File size
Size of a file in bytes as stored in git.
Finds unexpectedly large files, for example generated code or binaries checked into the repository.
Cyclomatic complexity
Sum of the cyclomatic complexity (McCabe) of all functions of a file: the number of independent paths through the code, counted by Lizard for about 25 languages.
Each path needs a test. Complex files are harder to test and to change safely. Combined with change frequency it shows the hotspots that matter most.
Cognitive complexity
Sum of the cognitive complexity of all functions of a file. Unlike cyclomatic complexity it weighs nesting, so deeply nested code counts more than flat code with the same number of branches.
Code that is hard to read is where misunderstandings and bugs happen, for people and for AI assistants alike. Tall red buildings are good candidates for refactoring.
AI written code
Which code came from AI coding assistants, and does anyone still understand it?
AI written code
Share of the lines of a file (by blame) whose last change came from a commit made with an AI coding assistant, detected by the assistant as author or co-author or by a generated footer. Inline completions leave no trace, so this is a lower bound.
AI written code is not a problem in itself, but nobody has written it by hand. Together with complexity and knowledge loss it shows where the team may not know its own code.
Comprehension debt
Share of the lines of a file (by blame) that no active person wrote or changed last: lines from AI assisted commits and lines of authors without a commit in the last 180 days.
Like knowledge loss, but AI counts as an author nobody can ask. Tall red buildings are code to review, test and explain before the next larger change.
Complexity of AI written code
Cognitive complexity of a file combined with its share of AI written lines.
Complex code is hard to review. If it came from an AI assistant, it may have been accepted without being fully understood. These files deserve a careful review first.