Table Of ContentJ
a
v
a
E
d
i
t
i
o
n
Building
Maintainable
Software
TEN GUIDELINES FOR FUTURE-PROOF CODE
Joost Visser
JAVA EDITION
Building Maintainable Software
Ten Guidelines for Future-Proof Code
Joost Visser
Boston
Building Maintainable Software: Ten Guidelines for Future-Proof Code
by Joost Visser
Copyright © 2016 Software Improvement Group, B.V. All rights reserved.
Printed in the United States of America.
Published by O’Reilly Media, Inc., 1005 Gravenstein Highway North, Sebastopol, CA 95472.
O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are
also available for most titles (http://safaribooksonline.com). For more information, contact our corporate/
institutional sales department: 800-998-9938 or corporate@oreilly.com.
Acquisitions Editor: Rachel Roumeliotis Indexer: WordCo Indexing Services, Inc.
Editor: Nan Barber Interior Designer: David Futato
Production Editor: Matthew Hacker Cover Designer: Randy Comer
Copyeditor: Rachel Monaghan Illustrator: Rebecca Demarest
Proofreader: Marta Justak
February 2016: First Edition
Revision History for the First Edition
2016-01-25: First Release
See http://oreilly.com/catalog/errata.csp?isbn=9781491940662 for release details.
The O’Reilly logo is a registered trademark of O’Reilly Media, Inc. Building Maintainable Software: Ten
Guidelines for Future-Proof Code, the image of a grey-headed woodpecker, and related trade dress are
trademarks of O’Reilly Media, Inc.
While the publisher and the authors have used good faith efforts to ensure that the information and
instructions contained in this work are accurate, the publisher and the authors disclaim all responsibility
for errors or omissions, including without limitation responsibility for damages resulting from the use of
or reliance on this work. Use of the information and instructions contained in this work is at your own
risk. If any code samples or other technology this work contains or describes is subject to open source
licenses or the intellectual property rights of others, it is your responsibility to ensure that your use
thereof complies with such licenses and/or rights.
978-1-4919-5352-5
[LSI]
Table of Contents
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 What Is Maintainability? 1
1.2 Why Is Maintainability Important? 3
1.3 Three Principles of the Guidelines in This Book 4
1.4 Misunderstandings About Maintainability 6
1.5 Rating Maintainability 7
1.6 An Overview of the Maintainability Guidelines 9
2. Write Short Units of Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.1 Motivation 13
2.2 How to Apply the Guideline 14
2.3 Common Objections to Writing Short Units 21
2.4 See Also 24
3. Write Simple Units of Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1 Motivation 32
3.2 How to Apply the Guideline 33
3.3 Common Objections to Writing Simple Units of Code 37
3.4 See Also 38
4. Write Code Once. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
4.1 Motivation 45
4.2 How to Apply the Guideline 45
4.3 Common Objections to Avoiding Code Duplication 50
4.4 See Also 53
iii
5. Keep Unit Interfaces Small. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5.1 Motivation 57
5.2 How to Apply the Guideline 58
5.3 Common Objections to Keeping Unit Interfaces Small 62
5.4 See Also 63
6. Separate Concerns in Modules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.1 Motivation 69
6.2 How to Apply the Guideline 70
6.3 Common Objections to Separating Concerns 73
7. Couple Architecture Components Loosely. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
7.1 Motivation 78
7.2 How to Apply the Guideline 82
7.3 Common Objections to Loose Component Coupling 84
7.4 See Also 86
8. Keep Architecture Components Balanced. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
8.1 Motivation 91
8.2 How to Apply the Guideline 92
8.3 Common Objections to Balancing Components 94
8.4 See Also 94
9. Keep Your Codebase Small. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
9.1 Motivation 98
9.2 How to Apply the Guideline 101
9.3 Common Objections to Keeping the Codebase Small 103
10. Automate Tests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
10.1 Motivation 109
10.2 How to Apply the Guideline 110
10.3 Common Objections to Automating Tests 119
10.4 See Also 121
11. Write Clean Code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
11.1 Leave No Trace 123
11.2 How to Apply the Guideline 124
11.3 Common Objections to Writing Clean Code 130
12. Next Steps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
12.1 Turning the Guidelines into Practice 133
iv | Table of Contents
12.2 Lower-Level (Unit) Guidelines Take Precedence Over Higher-Level
(Component) Guidelines 133
12.3 Remember That Every Commit Counts 134
12.4 Development Process Best Practices Are Discussed in the Follow-Up
Book 134
A. How SIG Measures Maintainability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Table of Contents | v
About the Authors
Joost Visser is Head of Research at the Software Improvement Group. In this role, he
is responsible for the science behind the methods and tools that SIG offers to measure
and master software. Joost also holds a position as professor of Large-Scale Software
Systems at Radboud University Nijmegen. He has obtained his PhD in Computer Sci‐
ence from the University of Amsterdam and has published over 100 papers on topics
such as generic programming, program transformation, green computing, software
quality, and software evolution. Joost considers software engineering a socio-
technical discipline, and he is convinced that software measurement is essential for
development teams and product owners to thrive.
Pascal van Eck joined the Software Improvement Group in 2013 as a general consul‐
tant on software quality. Prior to joining SIG, for 13 years Pascal was Assistant Pro‐
fessor of Information Systems at University of Twente, The Netherlands. Pascal holds
a PhD in Computer Science from Vrije Universiteit Amsterdam and has published
over 80 papers in areas such as enterprise architecture, IT security, and software met‐
rics. Pascal is chairman of the program committee of the Dutch National Conference
on Architecture for the Digital World.
After obtaining an MSc degree in Software Engineering from Delft University of
Technology in 2005, Rob van der Leek joined SIG as a software quality consultant.
Working at SIG is for Rob the closest thing to being a software doctor. In his role as a
consultant, he combines his thorough technical knowledge on software engineering
and software technologies to advise clients on how to keep their systems in shape.
Next to being a consultant, Rob fulfills a leading role in SIG’s internal development
team. This team develops and maintains the company’s software analysis tooling. It’s
Rob’s ambition to leave the IT industry a bit better than he found it.
Sylvan Rigal has worked as a software quality consultant at SIG since 2011 and has
advised clients on managing their IT since 2008. He helps clients achieve lower soft‐
ware maintenance costs and enhanced security by prioritizing improvements in soft‐
ware design and development processes. He holds a MSc in international business
from Maastricht University, The Netherlands. As an active member of SIG’s software
security team, Sylvan trains consultants on analyzing software security risks. When
he is not assessing the technical health of software, he is training in Brazilian jiu jitsu,
enjoying Amsterdam’s restaurants, or traveling through Asia. Approximately in that
order.
Gijs Wijnholds joined the Software Improvement Group in 2015 as a software qual‐
ity consultant in public administration. He helps clients get in control of their soft‐
ware projects by advising them on development processes and translating technical
risks into strategic decisions. Gijs holds a BSc in AI from Utrecht University and a
MSc degree in Logic from the University of Amsterdam. He is an expert on Haskell
and mathematical linguistics.
