Early praise for Software Design X-Rays Adam has made one of the most significant contributions to software engineering over the past years Listen and ye shall learn ➤ John Lewis Consultant and Troubleshooter Adam successfully teaches me why things are the way I have learned that they are during my 30 years in the software-development world As if that wasn’t enough, he also teaches me a whole slew of things I didn’t know about! This is a must-read! ➤ Jimmy Nilsson Author of Applying Domain-Driven Design and Patterns I felt my brain was exploding with ideas and ahas all the way through my reading ➤ Giovanni Asproni Principal Consultant Adam encapsulates the challenges of a technical lead for a product in a large shared codebase His social code-analysis techniques turn a dry static codebase into a living, breathing ecosystem and chart its interactions over its lifetime, helping you to identify those areas worth refactoring ➤ Ivan Houston Principal Software Engineer Adam takes you behind the scenes of pragmatic software analysis He’s bridging the gap between algorithms for mining software repositories and performing refactorings based on the gained insights Definitely the right way to go in our industry! ➤ Markus Harrer Software Development Analyst Software systems age and erode like any other human-made structure Software Design X-Rays provides immediately useable tools and approaches to spot the parts in most dire need of improvement and helps you manage your technical debt Adam does a great job at explaining that this seemingly complex analysis is actually not that hard and that you can it right now ➤ Michael Hunger Head of Developer Relations Engineering, Neo4j This book offers plenty of valuable psychological insights that are likely to surprise developers and managers alike Tornhill’s ability to apply heuristics like the “concept of surprise” to complex code systems reinforces the human element of software development and connects code to emotion ➤ Lauri Apple Open Source Evangelist and Agile Coach, Zalando An invaluable set of techniques to get a better understanding of your code, your team and your company Vicenỗ Garcớa Altộs IT Consultant, Craft Foster Ltd Software Design X-Rays Fix Technical Debt with Behavioral Code Analysis Adam Tornhill The Pragmatic Bookshelf Raleigh, North Carolina Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks Where those designations appear in this book, and The Pragmatic Programmers, LLC was aware of a trademark claim, the designations have been printed in initial capital letters or in all capitals The Pragmatic Starter Kit, The Pragmatic Programmer, Pragmatic Programming, Pragmatic Bookshelf, PragProg and the linking g device are trademarks of The Pragmatic Programmers, LLC Every precaution was taken in the preparation of this book However, the publisher assumes no responsibility for errors or omissions, or for damages that may result from the use of information (including program listings) contained herein Our Pragmatic books, screencasts, and audio books can help you and your team create better software and have more fun Visit us at https://pragprog.com The team that produced this book includes: Publisher: Andy Hunt VP of Operations: Janet Furlow Managing Editor: Brian MacDonald Supervising Editor: Jacquelyn Carter Development Editor: Adaobi Obi Tulton Copy Editor: Candace Cunningham Indexing: Potomac Indexing, LLC Layout: Gilson Graphics For sales, volume licensing, and support, please contact support@pragprog.com For international rights, please contact rights@pragprog.com Copyright © 2018 The Pragmatic Programmers, LLC All rights reserved No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form, or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior consent of the publisher Printed in the United States of America ISBN-13: 978-1-68050-272-5 Encoded using the finest acid-free high-entropy binary digits Book version: P1.0—March 2018 Contents Acknowledgments The World of Behavioral Code Analysis ix xi 3 10 13 Part I — Prioritize and React to Technical Debt Why Technical Debt Isn’t Technical Questioning Technical Debt The Perils of Quantifying Technical Debt Mine Your Organization’s Collective Intelligence Prioritize Improvements Guided by Data Identify Code with High Interest Rates Measure Interest Rates Prioritize Technical Debt with Hotspots Evaluate Hotspots with Complexity Trends Use X-Rays to Get Deep Insights into Code Escape the Technical-Debt Trap Exercises 15 15 19 24 27 31 33 Coupling in Time: A Heuristic for the Concept of Surprise Uncover Expensive Change Patterns Detect Cochanging Files The Dirty Secret of Copy-Paste The Power of Language-Neutral Analyses Exercises 35 35 37 44 46 48 Pay Off Your Technical Debt Follow the Principle of Proximity Refactor Congested Code with the Splinter Pattern Build Temporary Tests as a Safety Net 51 51 57 64 Contents Turn Hotspot Methods into Brain-Friendly Chunks The Curse of a Successful System The Principles of Code Age Stabilize Code by Age The Three Generations of Code Refactor Your Package Structure Scale from Files to Systems Exercises • vi 67 70 73 73 76 82 87 87 93 93 96 100 107 112 113 Part II — Work with Large Codebases and Organizations Spot Your System’s Tipping Point Is Software Too Hard? Divide and Conquer with Architectural Hotspots Analyze Subsystems Fight the Normalization of Deviance Toward Team-Oriented Measures Exercises Beyond Conway’s Law Software Architecture Is About Making Choices Measure Coordination Needs Code Ownership and Diffusion of Responsibility Analyze Operational Team Boundaries Social Groups: The Flip Side to Conway’s Law Combine Social and Technical Information Toward Modular Monoliths through the Social View of Code Dodge the Silver Bullet Layered Architectures and the Cost of Consistency Monolithic Alternatives: Use Case and Feature-Centric Discover Bounded Contexts Through Change Patterns The Perils of Feature Teams Clean and Dirty Architectures Exercises Systems of Systems: Analyzing Multiple Repositories and Microservices Analyze Code in Multiple Repositories 117 117 119 125 129 134 138 141 141 144 147 151 155 161 162 165 165 Contents Compare Hotspots Across Repositories Track Change Patterns in Distributed Systems Measure Technical Sprawl Distribution Won’t Cure the Dependency Blues Exercises • vii 170 173 180 185 187 10 An Extra Team Member: Predictive and Proactive Analyses Detect Deviating Evolutionary Patterns Catch the Absence of Change Guide On- and Offboarding with Social Data Know the Biases and Workarounds for Behavioral Code Analysis Your Code Is Still a Crime Scene Exercises 189 189 197 200 A1 The Hazards of Productivity and Performance Metrics Adaptive Behavior and the Destruction of a Data Source The Situation Is Invisible in Code 211 211 212 A2 Code Maat: An Open Source Analysis Engine Run Code Maat Data Mining with Code Maat Visualizations 215 215 215 217 A3 Data Mining with Git, cloc, and CodeScene Behavioral Code Analysis with Git A Brief Introduction to cloc Export Analysis Data from CodeScene 221 221 223 224 A4 Hints and Solutions to the Exercises Solutions: Identify Code with High Interest Rates Solutions: Coupling in Time Solutions: The Principles of Code Age Solutions: Spot Your System’s Tipping Point Solutions: Modular Monoliths Solutions: Systems of Systems Solutions: An Extra Team Member 227 227 228 229 229 230 232 232 235 239 Bibliography Index 205 207 209 Acknowledgments Writing a book is a lot like programming in the sense that it’s an iterative process where most of the work is rework Since Software Design X-Rays is my fourth book I sort of knew the effort and time it would take Or at least I thought I did, as it turned out to be so much harder than I initially expected (Again a bit like programming, isn’t it?) At the end it was worth every minute and I’m really proud of the book you’re reading right now That wouldn’t have been possible without all the wonderful people who helped me make this book much better than what I could have done on my own I’d like to thank The Pragmatic Bookshelf for this opportunity I also want to thank my editor, Adaobi Obi Tulton, for all her support, motivation, and great work in shaping the book Several people volunteered their time and expertise by reading early drafts of the book: Jimmy Nilsson, Giovanni Asproni, Ivan Houston, Markus Harrer, Michael Hunger, Lauri Apple, Per Rovegård, Joseph Fahey, Louis Hansen, Vicenỗ Garcớa Altộs, Nascif Abousalh-Neto, Clare Macrae, Michael Keeling, Alberto Fernandez Reyes, Javier Collado, and Ian Sleigh Thanks for all your helpful advice and constructive criticism Over the past years I’ve been contacted by people from all around the globe who’ve read my previous work or watched my presentations Thanks to all of you—your feedback and friendly words are what motivates me to keep doing this The same goes for my amazing colleagues at Empear and for my fantastic parents, Eva and Thorbjörn, who always encourage and support me Finally, I want to thank my family—Jenny, Morten, and Ebbe—for their endless love and support You mean everything to me and I love you report erratum • discuss Index experts, identifying, 200, 210, 233 external protocols, 57 Extract Method, 70 The eyes have it, 201 F familiarity, conservation of, 180 Feathers, Michael, feature-based teams cautions, 155–161 vs component-based teams, 118 features DCI paradigm, 150 fractal value analysis and new, 124 package by feature, 148– 151 removing obsolete features during rewrites, 143 testing decoupling by deleting features, 150 feedback loops, feature-based teams, 159 files enclosure diagrams, 20 file-level analysis of team contributions and coordination, 132 generating lines of code by file, 224 names and analyzing change on architectural level, 145 using name prefixes when analyzing across multiple repositories, 170, 175 virtual root, 170, 175 filters, component-oriented architecture, 148 find command, 120 folders calculating number of contributors to, 223 enclosure diagrams, 19 mapping architectural boundaries, 98 mapping logical components, 98, 216, 222 measuring coordination, 120 forensic hotspots, 207, see also hotspots forgetting curve, Ebbinghaus, 77, 93 format option, 17, 75 forward slash (/), escaping, 99 Fractal Figures, 122, 124 fractal value analysis aliases and, 125, 130 ranking code by diffusion, 122–123 study on number of defects, 124 technical sprawl index, 184 fractal value formula, 122, 184 fragmentation, developer handling, 124–125 identifying, 122 function as a service architecture, 186 functions and methods, see also proximity principle; XRay analysis refactoring with code age, 81 refactoring with splinter pattern, 60–62 specifying by lines of code, 104, 222 weighted method complexity, 192–195 fundamental attribution error, 24, 137 G gatekeepers, 160 geographical offender profile, 207 Gestalt psychology, 54 Git aliases, removing, 125, 130 architectural boundaries, identifying, 97–100 author distribution, 202 change coupling across multiple repositories, 173–180 change coupling analysis, 36–46, 173–180, 199 change coupling to catch omissions, 199 change frequency, calculating, 17, 222 • 244 code age, calculating, 75, 223 Code Maat, running, 216 commands, 221–223 commit count per contributor, calculating, 120, 122, 129 complexity warnings, 193–195 contributors, calculating number of, 94, 120, 223 coordination, measuring, 120 detecting future hotspots, 195–197 excluding autogenerated content, 76 excluding by path, 100 fractal value analysis, 122, 125, 129–130 hotspot exercise, 188, 232 hotspots across multiple repositories, comparing, 170–173 hotspots in multiple repositories, analyzing, 165–170 hotspots, aggregating, 96, 222 hotspots, identifying, 19– 23, 221 knowledge loss, measuring, 202, 223 knowledge maps, creating, 157 logical change sets, 175 offboarding exercise, 210, 233 operational boundaries, analyzing, 129 pre-commit hooks, 195, 199 programming-language sprawl, measuring, 182, 184 removing empty lines, 17, 221 resources on, 222 restricting data by date, 64, 98, 129, 196, 221 specifying revisions by lines of code, 104, 222 subsystems, running analyses on, 221 temporary migrations to, xii Index tree maps, 21 X-Ray analysis tips, 104, 222 Git Version Control Cookbook, 17 GitHub, case studies hosting, xv glob patterns, 99 goals avoiding team conflicts, 138 motivation loss and, 135 Google, see TensorFlow examples grep, 222 group option, 217 group conflicts, 134, 137, 170 Group Process and Productivity, 125 Group Process, Group Decision, Group Action, 138 Growing Object-Oriented Software, Guided by Tests, 31 H Halstead complexity measures, 18, see also complexity Hamano, Junio, 233 Hickey, Rich, 210, 233 hierarchical edge bundle, 38 hooks, pre-commit, 195, 199 hotspots about, 15 aggregating, 96, 108– 111, 222 aggregating with complexity trend analysis for whistleblower, 108–111 architectural, 96–104, 113–115, 144–147, 229 audiences, 32 causes, 32, 57 code ownership and, 126 complexity trend analysis, 24–26, 28, 57, 85, 101–104 defined, 19 detecting future, 195–197 duration of, 33 evolution, 111 exercises, 33–34, 113– 115, 188, 227, 229, 232 file-level analysis vs method-level, 27 forensic, 207 identifying, 19–23, 221 knowledge loss, 205 largest, 189–197 layered architecture example, 144–147 microservices, analyzing, 165–170 microservices, comparing in, 170–173 ranking rising, 196 refactoring package structure with code age, 82–86 refactoring with chunking, 67–70 refactoring with splinter pattern, 57–64 splitting along responsibilities, 60 subsystems, analyzing, 100–107 temporary tests as safety net, 64–67 uses, 31 visualizations, 19–21, 111, 219 working with untouchable code, 32 X-Ray analysis, 27–31, 114, 229 How Buildings Learn, 73 human memory, see memory, human I ignorant surgery, 78 immutable design and code ownership and, 126 Implementation Patterns, 69 indentation-based complexity, 25 index, technical sprawl, 183– 185 The Influence of Organizational Structure on Software Quality, 9, 119 integration tests, team contributions and coordination, 132 interest rate, technical debt measuring, 15–19 understanding, 4–5 internal protocols, 57 • 245 isolation countering, 134–138 isolating code by age, 79– 82 microservices, 186 J Java clone detectors, 45 running Code Maat, 215 JSON, generating for visualizations with Code Maat, 218 K knowledge boundaries, see also knowledge maps; knowledge sharing avoiding team conflicts, 138 broadening, 128 code ownership and, 127 knowledge loss, 204 onboarding and offboarding, 200 vs operational boundaries, 128 vs parallel development, 10 technical sprawl and, 182 knowledge loss, 202–205, 223 knowledge maps, see also knowledge boundaries; knowledge sharing analyzing on team level with Code Maat, 217 building, 157–159, 217 identifying experts, 200 limits of Conway’s law, 134 performance reviews and, 137, 211 understanding, 11 uses, 156–157 knowledge sharing, see also knowledge boundaries; knowledge maps avoiding team conflicts, 138 code ownership and, 128 rotating teams, 10 technical sprawl and, 181–185 Index Kotlin knowledge map example, 201 power law distribution, 202 Kubernetes locating experts exercise, 210, 233 L -L option, 104, 222 languages, programming change coupling analysis, 46 community and, 185 power of language-neutral analyses, 46 separating mixed for splinter refactoring, 61 technical sprawl and, 181–185 using polyglot as deliberate choice, 183 layered architecture flexibility, 147 identifying bounded contexts, 152–154 separation of concerns, 146 understanding before rewriting, 144–147 Lean Architecture for Agile Software Development, 150 legacy code defined, quality of code and prioritizing hotspots, 22 from rewrites, 142 vs technical debt, Lehman, Manny, 180 Lehman’s laws, 180 libraries hotspot analysis on, 32 isolating code by age, 79– 82 lines, removing blank lines from data, 17, 221 lines of code analyzing hotspots across multiple repositories, 167 cloc commands, 19, 223 as complexity metric, 18 complexity of large systems, 96 identifying hotspots, 19 knowledge maps, 157 measuring programminglanguage sprawl, 182, 184 specifying revisions by, 104, 222 summarizing change frequencies of logical components, 99 visualizations with Code Maat example, 218 Lint, 62 Linux and the Unix Philosophy, 185 Linux kernel about, xiv aggregating hotspots and complexity trend analysis for whistleblower, 108–111 analyzing subsystem examples, 100–107, 221 architectural hotspots example, 96–100 architectural hotspots exercise, 114, 229 coordination example, 120–125 fractal value analysis example, 122–123 number of contributors, 94, 124 system-level refactoring example, 94–107 visualizing architectural boundaries, 100 loafing, social, 135 log calculating change frequency, 17 calculating code age, 75, 223 identifying architectural boundaries, 97–100 summarizing data with shortlog, 120 tree maps, 21 log, decision, logical change sets, 175 logical components architectural boundaries as, 98 change frequencies, summarizing, 99 change patterns on architectural level, identifying, 144–147, 216 • 246 complexity trend analysis as whistleblower, 108– 111 defining in microservices, 166 mapping subfolders to, 98, 216, 222 technical sprawl and knowledge loss, 205 visualizations, 111 M mailmap, 125, 130 maintainability code coverage warning signs, 66 end-to-end tests, 66 feature-based teams, 160 layered architecture, 144 predicting problems with increases in complexity, 193 Making Software, 18 McCabe cyclomatic complexity, 18, see also cyclomatic complexity median code age, 89, 229 memory, human chunks and working memory, 67, 93 code age and, 74, 76–78 decision log, difficulty of programming and, 93 Ebbinghaus forgetting curve, 77, 93 schemas, 8, 77 mental models of code, messages, commit, see commit messages methods, see functions and methods; proximity principle; X-Ray analysis microservices about, 165 avoiding conflicts with UI, 176–178 change coupling, 170, 173–180 cohesion, 166 collapsing, 180 complexity trend analysis, 168 consistency, 148 dependencies, detecting implicit, xii, 175, 179 exercises, 187–188, 232 Index hotspots, analyzing, 165– 170 hotspots, comparing, 170–173 organizing by higher-level concepts, 179 ownership, 180 shotgun surgery, 178 size, 166 splitting, 170 standardizing ecosystem, 181 team organization, 170, 174, 179 technical sprawl, 180– 185 warning signs, 166 Microsoft, coordination research, 119, see also ASP.NET Core MVC middleware, publish-subscribe, 186 Mining Version Histories to Guide Software Changes, 47 The Mirroring Hypothesis, 128 mob programming, bias in analyses, 207 mock objects, problems with, 30 model-view controller (MVC) architecture change patterns of layered architecture example, 145–147 difficulties changing, 141 modularity aligning boundaries with responsibilities, 118 coordination and, 95 modules chunking by code age, 81, 86 refactoring with splinter pattern, 60–61 motivation loss countering, 135–137, 182 feature-based teams, 159 process loss and, 125 from rewrites, 143 Mozilla, 124 MusicStore example of layered architecture, 144–147 MVC (model-view controller) architecture change patterns of layered architecture example, 145–147 difficulties changing, 141 The Mythical Man-Month, 94 N names aliases and fractal value analysis, 125, 130 chunking by code age, 81, 88, 229 file names and analyzing change on architectural level, 145 generic names and low cohesion, 62, 173 glob patterns, 99 logical components, 98, 216 operational boundaries, analyzing, 129 provisional tests, 66 refactoring with chunking, 68 refactoring with splinter pattern, 62 using prefixes when analyzing across multiple repositories, 170, 175 NDepend, 61 NET clone detectors, 45 examples, 189–197 No Silver Bullet, xii nontechnical managers communication with, 95, 111 fractal value analysis, 124 hotspot analysis of microservices, 173 knowledge maps, 157 raising abstraction level to communicate with, 95 visualizations and, xii, 111 nopCommerce change coupling exercise, 162, 230 identifying bounded contexts example, 152–154 normalization of deviance, 107–108 • 247 North, Dan, 76 numstat option, 157 O object roles, 150 Ochsenreither, Simon, 203– 204 offboarding, 200–205, 210, 233 omissions, catching, 49, 197– 200, 228 On Finding Duplication and Near-Duplication in Large Software Systems, 45–46 On Understanding Laws, Evolution, and Conservation in the Large-Program Life Cycle, 180 onboarding, 200–205 open source collaboration code ownership and, 127 organization issues and defects, operational boundaries analyzing, 129–133 change coupling in microservices, 174 component-oriented architecture, 148 Conway’s law and knowledge maps, 134 DCI paradigm, 150 focusing on team-level metrics, 207 vs knowledge boundaries, 128 knowledge maps, 156– 161 organizational issues, see also team organization knowledge distribution, 10 predictors of defects, size and increase in challenges, 94 vs technical issues, P package by component, 148– 151 package by feature, 148–151 packages isolating code by age, 79– 82 Index packaging to reduce dependencies in microservices, 178 refactoring by code age, 73–89 pair programming, bias in analyses, 139, 207 parallel development bias in analyses, 207 conflict with refactoring, 59 coordination example, 120–125 development congestion, effect on quality, file-level analysis of team contributions and coordination, 132 fractal value analysis, 124, 130 vs knowledge distribution, 10 limiting analysis by date, 223 mapping, 12 Parnas, David, 78 peer reviews, performance evaluation cautions about judging code in retrospect, 24 cautions about knowledge maps, 137, 211 general cautions, 211– 214 peer reviews, Phillips, Paul, 203–204 PhpSpreadsheet architectural hotspot exercise, 115, 230 change coupling exercise, 162, 231 pipes, component-oriented architecture, 148 play, prototyping as, 182 PMD, 61 power law distribution developers, 202 prioritizing with, 16 splinter modules, 64 The Pragmatic Programmer, 37 pre-commit hooks, 195, 199 Predicting fault incidence using software change history, 78 predictive analyses catching absence of change, 197–200 detecting evolutionary patterns, 189–197 detecting future hotspots, 195–197 exercises, 209, 232 increases in complexity, 192–195 privatization, diffusion of responsibility and, 126 proactive analyses exercises, 209, 232 onboarding and offboarding, 200–205, 210, 233 problem domain vs solution domain, 118 users and understanding, 157 process loss, 125, 159 processes, Erlang, 114 Processing, visualizations with, 218 Production-Ready Microservices, 170, 181 productivity congruence and, 118 process loss and, 125 programming, difficulty of, 93–96 protocols and coupling, 179– 180 prototyping as play, 182 provisional tests, 64–67 proximity principle automating recommendations, 56 Gestalt psychology, 54 logical change sets, 175 refactoring with, 51–57 refactoring with splinter pattern, 60 publish-subscribe middleware, 186 Python clone detectors, 45 complexity trend analysis script, 26 refactoring package structure with code age example, 82–86 version, 218 visualizations with Code Maat example, 218 • 248 Q quality of code cautions about judging in retrospect, 24 code ownership and, 121, 127 legacy code and prioritizing hotspots, 22 normalization of deviance, 107–108 organizational factors, parallel development, support for change, 35 test code, 43 quiet option, 223 R Rabin–Karp algorithm, 45 Rails calculating change frequency example, 17 calculating code age example, 75 complexity analysis exercise, 34, 227 readability as economical, indentation, 25 for maintenance, Reading Beside the Lines, 25 reckless debt, recognition, social loafing and, 136 refactoring, 51–71, see also rewrites about, xii architectural hotspots, 96–104 by code age, 73–89 with chunking, 67–70 conflict with parallel development, 59 control coupling, 30 databases, 155 DCI paradigm, 150 package structure with code age, 82–86 proximity principle, 51– 57 resources on, 58 with splinter pattern, 57– 64, 81, 124 system-level example, 94– 107 temporary tests as safety net, 64–67 Index tracking effects with aggregated trends, 110 tracking effects with complexity trend analysis, 227 Refactoring Databases, 155 Refactoring for Software Design Smells, 58 Refactoring: Improving the Design of Existing Code, 58, 63, 178 Reflective Practitioner, 169 regular expressions, mapping folders to logical components, 99, 216 replacement systems, see rewrites report-file option, 224 repositories, multiple aggregating contributions per repository, 167–170 analyzing hotspots in, 165–170 bias of copy-past repositories, 206 change coupling, 173– 180 requirements, capturing for rewrites, 143 resources for this book, xvi cloc, 223 Git, 222 refactoring, 58 responsibilities aligning boundaries with, 118 bounded contexts, 154 Conway’s law and knowledge maps, 134 diffusion of responsibility, 125–129, 135, 160 feature-based teams, 160 fractal value analysis, 124 identifying architectural boundaries, 98 increases in complexity, 195 isolation and, 134 layered architecture, 147 microservices, 166, 168– 169 new teams and shared, 131–133 refactoring with code age, 81 rotating, 10 social loafing, 135 splitting hotspots along, 60 symmetry between organization and design, 131 rev-list, 167, 222 reviews, code, see code reviews revisions, 218 rewrites, see also refactoring databases and, 155 DCI paradigm, 150 exercises, 162, 230 identifying bounded contexts, 151–154 need for, 141–144 package by component/feature, 148–151 removing obsolete features, 143 trade-offs, 142–144 understanding layers of architecture before, 144–147 Ringelmann effect, 135 rising hotspots, detecting, 195–197 risk code age and, 78 communicating risks to nontechnical managers, 111 normalization of deviance, 107 proximity refactoring, 57 rewriting architecture, 142–144 Roslyn catching omissions example, 197–200 change coupling analysis exercise, 48, 228 rotating teams avoiding gatekeepers, 161 avoiding team conflicts, 138 broadening knowledge boundaries, 128 knowledge distribution, 10 Ruby on Rails calculating change frequency example, 17 calculating code age example, 75 • 249 S -s option, 120, 122, 129 Scala example of knowledge loss, 203–204 schemas, 8, 77 Secure open source collaboration, 9, 124 security, number of developers and, 124 sed, 171 Selenium, 65 separation of concerns, layered architecture, 146 serverless architecture, 186 shells, running Code Maat, 216 shortlog analyzing operational boundaries, 129 author distribution, 202 calculating number of contributors, 94, 223 coordination, measuring, 120 fractal value analysis, 122, 129 shotgun surgery, microservices, 178 Sikuli, 65 silos, development, 126, 172, 204 silver bullets, xii Simian, 45 size analyzing hotspots across multiple repositories, 167 complexity of large systems, 94, 96 complexity warnings, 195 microservices, 166 rising hotspots, 196 system size and increase in challenges, 94 team size and minimizing social loafing, 136 slashes, escaping, 99 social loafing, 135 Software Aging, 78 Software Design: Cognitive Aspects, software half-life, 76 solution domain vs problem domain, 118 Index SonarQube, 61 space shuttle Challenger, 107–108 spaghetti code, 191 Spinnaker change coupling exercises, 187, 232 comparing hotspots across multiple repositories example, 171– 173 detecting implicit dependencies example, 176 technical sprawl example, 182–185 splinter pattern accessing directly, 63 cautions, 64 context and consequences, 63 identifying refactoring needs with fractal value analysis, 124 names, 62 refactoring with, 57–64, 81, 124 separating code with mixed content, 61 sprawl, technical, xii, 180– 185, 205 squash commits, 206 standards, parallel development, static analysis tools, 61 strings, refactoring with chunking, 70 subsystems analyzing hotspots, 100– 107 audiences, 96 divide and conquer strategy, 96–100 running analyses on with Git, 221 surprise change coupling analysis, 38 logical change sets, 175 system-level refactoring architectural hotspots, 96–104 Linux kernel example, 94–107 T tabs, indentation-based complexity, 25 task identifiers, logical change sets, 175 team organization, see also bottlenecks; code ownership; communication; knowledge boundaries; knowledge maps; operational boundaries aligning boundaries with responsibilities, 118 analyzing contributions by team, 131 coffee breaks, 138 component-based teams vs feature-based teams, 118 conflicts, 134, 137, 170 Conway’s law, 117 countering isolation, 134–138 cross-organizational groups, 174 diffusion of responsibility, 125–129, 135, 160 feature-based teams, 118, 155–161 focusing on team-level metrics, 207 gatekeepers, 160 identifying experts, 200, 210, 233 knowledge loss, 202– 205, 223 measuring coordination needs, 119–125 microservices, 170, 174, 179 motivation loss, 125, 135–137, 143, 159, 182 onboarding and offboarding, 200–205, 210, 233 performance evaluation cautions, 24, 137, 211– 214 predictors of rate of defects and, 119 process loss and, 125, 159 ranking code by diffusion, 122–123 rewrites and, 142 rotating teams, 10, 128, 138, 161 • 250 shared responsibilities, 131–133 team size, 136 team-definition file, Code Maat, 217 team-map-file flag, 217 technical debt about, xi vs bad code, as choice, 3–4 decision log, defined, interest rate, 4–5, 15–19 vs legacy code, on creation, 189, 191 prioritizing with hotspots, 19–23, 31 prioritizing with power law distribution, 16 prioritizing, need for, xi, 10 problems with quantifying, 6–9 reckless debt, understanding, 3–14 technical sprawl, xii, 180– 185, 205 temporal coupling vs change coupling, 37 TensorFlow about, xiv change coupling analysis exercise, 49, 228 code age example, 79–82 code age exercise, 88, 229 tests architectural hotspot exercise, 115, 230 change coupling analysis, 43 code coverage warning signs, 66 deleting unit tests, 67 Docker exercise, 33, 227 documenting behavior with unit, 22 end-to-end tests, 65–67 file-level analysis of team contributions and coordination, 132 fractal value analysis, 124 prioritizing with code age, 74 problems with mocks and unit, 31 Index quality of test code, 43 refactoring with splinter pattern, 60 splitting by responsibility, 133 starting with unit, 31 temporary tests as safety net, 64–67 test cases and aging, 79 testing decoupling by deleting features, 150 walkthroughs to catch code early, 192 third-party code, hotspot analysis on, 32 thresholds change coupling to catch omissions, 199 complexity warnings, 193–194 rising hotspots, 196 tickets, logical change sets, 175 time, see also code age change coupling analysis, 35, 40 complexity trend analysis, 24–26, 193–195 complexity warnings, 193–195 as data factor, 12, 21 dimension of hotspots, 21 interest rate of technical debt, 4–5 logical change sets, 175 prioritizing clones, 46 rising hotspots, 196 tipping point complexity trend analysis as whistleblower, 108– 111 identifying, 93 To Mock or Not to Mock?, 31 Tomcat complexity warning exercise, 209, 232 Torvalds, Linus, 210, 233 tree maps, 21, 219 trees, abstract syntax, 45 U Über das Gedächtnis, 77 unit tests architectural hotspot exercise, 115, 230 deleting, 67 Docker exercise, 33, 227 documenting behavior with, 22 problems with mocks, 31 starting with, 31 unix flag, 224 use cases bounded contexts, 151 DCI paradigm, 150 user interface (UI) avoiding conflicts with microservices, 176–178 back end for front end (BFF) pattern, 177 composite, 177 package by component/feature pattern, 149 users, understanding problem domain, 157 UTF-8, 216 V Vaughan, Diane, 107 version-control system, see also Code Maat; Git; visualizations alternatives to Git, xii biases within, 205 as data source, xiv, 10– 13 knowledge loss, measuring, 202 virtual root, 170, 175 Visual Basic, change coupling analysis exercise, 48, 228 Visual Studio Code knowledge map example, 12 visualizations, see also knowledge maps architectural boundaries, 100 change coupling analysis, 38, 40 code age, 80 Code Maat and, 217 dependency wheels, 40 enclosure diagrams, 19, 80, 122, 218 fractal value analysis of author contributions, 122 hierarchical edge bundle, 38 hotspots, 19–21, 111, 219 importance of, 111 • 251 nontechnical managers and, xii, 111 with Processing, 218 technical sprawl, 183 tree maps, 21, 219 W walkthroughs broadening knowledge boundaries, 128 when to perform, 192 warnings catching absence of change, 197–200 complexity whistleblower, 108–111 ignore option for, 199 of increases in complexity, 193–195, 209, 232 wc -l utility, 120, 222 weighted method complexity, 192–195 When and Why Your Code Starts to Smell Bad, 191 whistleblower, complexity trend analysis as, 108–111 whitespace indentation-based complexity, 25 refactoring with chunking, 69 wildcards, 99 Windows, using cloc and UNIX path style, 224 Working Effectively with Legacy Code, 4, 58 X X-Ray analysis architectural hotspot exercise, 114, 229 bounded contexts, identifying, 153, 162, 230 change coupling across multiple repositories, 177 change coupling analysis, 40–46, 49, 177, 228 clones, identifying system-level, 104–106 code age refactoring of package structure, 85 complexity trends, 28 dependency wheel visualizations, 40 exercises, 49, 162, 228, 230 Index with Git, 104, 222 hotspots, 27–31, 114, 229 prioritizing functions in system-level analysis, 102 refactoring with chunking, 68 refactoring with splinter pattern, 60 • 252 Y Your Code as a Crime Scene, xiv, 207 Thank you! How did you enjoy this book? Please let us know Take a moment and email us at support@pragprog.com with your feedback Tell us your story and you could win free ebooks Please use the subject line “Book Feedback.” Ready for your next great Pragmatic Bookshelf book? Come on over to https://pragprog.com and use the coupon code BUYANOTHER2018 to save 30% on your next ebook Void where prohibited, restricted, or otherwise unwelcome Do not use ebooks near water If rash persists, see a doctor Doesn’t apply to The Pragmatic Programmer ebook because it’s older than the Pragmatic Bookshelf itself Side effects may include increased knowledge and skill, increased marketability, and deep satisfaction Increase dosage regularly And thank you for your continued support, Andy Hunt, Publisher SAVE 30%! Use coupon code BUYANOTHER2018 Better by Design From architecture and design to deployment in the harsh realities of the real world, make your software better by design Design It! Don’t engineer by coincidence—design it like you mean it! Grounded by fundamentals and filled with practical design methods, this is the perfect introduction to software architecture for programmers who are ready to grow their design skills Ask the right stakeholders the right questions, explore design options, share your design decisions, and facilitate collaborative workshops that are fast, effective, and fun Become a better programmer, leader, and designer Use your new skills to lead your team in implementing software with the right capabilities—and develop awesome software! Michael Keeling (358 pages) ISBN: 9781680502091 $41.95 https://pragprog.com/book/mkdsa Release It! Second Edition A single dramatic software failure can cost a company millions of dollars—but can be avoided with simple changes to design and architecture This new edition of the best-selling industry standard shows you how to create systems that run longer, with fewer failures, and recover better when bad things happen New coverage includes DevOps, microservices, and cloud-native architecture Stability antipatterns have grown to include systemic problems in large-scale systems This is a must-have pragmatic guide to engineering for production systems Michael Nygard (376 pages) ISBN: 9781680502398 $47.95 https://pragprog.com/book/mnee2 Learn Why, Then Learn How Get started on your Elixir journey today Adopting Elixir Adoption is more than programming Elixir is an exciting new language, but to successfully get your application from start to finish, you’re going to need to know more than just the language You need the case studies and strategies in this book Learn the best practices for the whole life of your application, from design and team-building, to managing stakeholders, to deployment and monitoring Go beyond the syntax and the tools to learn the techniques you need to develop your Elixir application from concept to production Ben Marx, José Valim, Bruce Tate (225 pages) ISBN: 9781680502527 $42.95 https://pragprog.com/book/tvmelixir Programming Elixir ≥ 1.6 This book is the introduction to Elixir for experienced programmers, completely updated for Elixir 1.6 and beyond Explore functional programming without the academic overtones (tell me about monads just one more time) Create concurrent applications, but get them right without all the locking and consistency headaches Meet Elixir, a modern, functional, concurrent language built on the rock-solid Erlang VM Elixir’s pragmatic syntax and built-in support for metaprogramming will make you productive and keep you interested for the long haul Maybe the time is right for the Next Big Thing Maybe it’s Elixir Dave Thomas (398 pages) ISBN: 9781680502992 $47.95 https://pragprog.com/book/elixir16 A Better Web with Phoenix and Elm Elixir and Phoenix on the server side with Elm on the front end gets you the best of both worlds in both worlds! Functional Web Development with Elixir, OTP, and Phoenix Elixir and Phoenix are generating tremendous excitement as an unbeatable platform for building modern web applications For decades OTP has helped developers create incredibly robust, scalable applications with unparalleled uptime Make the most of them as you build a stateful web app with Elixir, OTP, and Phoenix Model domain entities without an ORM or a database Manage server state and keep your code clean with OTP Behaviours Layer on a Phoenix web interface without coupling it to the business logic Open doors to powerful new techniques that will get you thinking about web development in fundamentally new ways Lance Halvorsen (218 pages) ISBN: 9781680502435 $45.95 https://pragprog.com/book/lhelph Programming Elm Elm brings the safety and stability of functional programing to front-end development, making it one of the most popular new languages Elm’s functional nature and static typing means that run-time errors are nearly impossible, and it compiles to JavaScript for easy web deployment This book helps you take advantage of this new language in your web site development Learn how the Elm Architecture will help you create fast applications Discover how to integrate Elm with JavaScript so you can update legacy applications See how Elm tooling makes deployment quicker and easier Jeremy Fairbank (250 pages) ISBN: 9781680502855 $40.95 https://pragprog.com/book/jfelm Pragmatic Programming We’ll show you how to be more pragmatic and effective, for new code and old Your Code as a Crime Scene Jack the Ripper and legacy codebases have more in common than you’d think Inspired by forensic psychology methods, this book teaches you strategies to predict the future of your codebase, assess refactoring direction, and understand how your team influences the design With its unique blend of forensic psychology and code analysis, this book arms you with the strategies you need, no matter what programming language you use Adam Tornhill (218 pages) ISBN: 9781680500387 $36 https://pragprog.com/book/atcrime The Nature of Software Development You need to get value from your software project You need it “free, now, and perfect.” We can’t get you there, but we can help you get to “cheaper, sooner, and better.” This book leads you from the desire for value down to the specific activities that help good Agile projects deliver better software sooner, and at a lower cost Using simple sketches and a few words, the author invites you to follow his path of learning and understanding from a half century of software development and from his engagement with Agile methods from their very beginning Ron Jeffries (176 pages) ISBN: 9781941222379 $24 https://pragprog.com/book/rjnsd The Pragmatic Bookshelf The Pragmatic Bookshelf features books written by developers for developers The titles continue the well-known Pragmatic Programmer style and continue to garner awards and rave reviews As development gets more and more difficult, the Pragmatic Programmers will be there with more titles and products to help you stay on top of your game Visit Us Online This Book’s Home Page https://pragprog.com/book/atevol Source code from this book, errata, and other resources Come give us feedback, too! Register for Updates https://pragprog.com/updates Be notified when updates and new books become available Join the Community https://pragprog.com/community Read our weblogs, join our online discussions, participate in our mailing list, interact with our wiki, and benefit from the experience of other Pragmatic Programmers New and Noteworthy https://pragprog.com/news Check out the latest pragmatic developments, new titles and other offerings Buy the Book If you liked this eBook, perhaps you’d like to have a paper copy of the book It’s available for purchase at our store: https://pragprog.com/book/atevol Contact Us Online Orders: https://pragprog.com/catalog Customer Service: support@pragprog.com International Rights: translations@pragprog.com Academic Use: academic@pragprog.com Write for Us: http://write-for-us.pragprog.com Or Call: +1 800-699-7764 ... understanding of your code, your team and your company Vicenỗ Garcớa Altộs IT Consultant, Craft Foster Ltd Software Design X-Rays Fix Technical Debt with Behavioral Code Analysis Adam Tornhill... in Code 211 211 212 A2 Code Maat: An Open Source Analysis Engine Run Code Maat Data Mining with Code Maat Visualizations 215 215 215 217 A3 Data Mining with Git, cloc, and CodeScene Behavioral. .. Acknowledgments The World of Behavioral Code Analysis ix xi 3 10 13 Part I — Prioritize and React to Technical Debt Why Technical Debt Isn’t Technical Questioning Technical Debt The Perils