Building Maintainable Software, Java Edition

Building Maintainable Software, Java Edition

by Joost Visser, Sylvan Rigal, Rob van der Leek, Pascal van Eck, Gijs Wijnholds
Released January 2016
Publisher(s): O'Reilly Media, Inc.
ISBN: 9781491953495

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

Have you ever felt frustrated working with someone else’s code? Difficult-to-maintain source code is a big problem in software development today, leading to costly delays and defects. Be part of the solution. With this practical book, you’ll learn 10 easy-to-follow guidelines for delivering Java software that’s easy to maintain and adapt. These guidelines have been derived from analyzing hundreds of real-world systems.

Written by consultants from the Software Improvement Group (SIG), this book provides clear and concise explanations, with advice for turning the guidelines into practice. Examples for this edition are written in Java, while our companion C# book provides workable examples in that language.

  • Write short units of code: limit the length of methods and constructors
  • Write simple units of code: limit the number of branch points per method
  • Write code once, rather than risk copying buggy code
  • Keep unit interfaces small by extracting parameters into objects
  • Separate concerns to avoid building large classes
  • Couple architecture components loosely
  • Balance the number and size of top-level components in your code
  • Keep your codebase as small as possible
  • Automate tests for your codebase
  • Write clean code, avoiding "code smells" that indicate deeper problems

Publisher resources

View/Submit Errata

Table of contents

  1. Preface
    1. The Topic of This Book: Ten Guidelines for Building Maintainable Software
    2. Why You Should Read This Book
    3. Who Should Read This Book
    4. What This Book Is Not
    5. The Follow-up Book
    6. About the Software Improvement Group
    7. About This Edition
    8. Related Books
    9. Conventions Used in This Book
    10. Generic Names for Elements of Source Code
    11. Using Code Examples
    12. Safari® Books Online
    13. How to Contact Us
    14. Acknowledgments
  2. 1. Introduction
    1. What Is Maintainability?
      1. The Four Types of Software Maintenance
    2. Why Is Maintainability Important?
      1. Maintainability Has Significant Business Impact
      2. Maintainability Is an Enabler for Other Quality Characteristics
    3. Three Principles of the Guidelines in This Book
      1. Principle 1: Maintainability Benefits Most from Simple Guidelines
      2. Principle 2: Maintainability Is Not an Afterthought, and Every Contribution Counts
      3. Principle 3: Some Violations Are Worse Than Others
    4. Misunderstandings About Maintainability
      1. Misunderstanding: Maintainability Is Language-Dependent
      2. Misunderstanding: Maintainability Is Industry-Dependent
      3. Misunderstanding: Maintainability Is the Same as the Absence of Bugs
      4. Misunderstanding: Maintainability Is a Binary Quantity
    5. Rating Maintainability
    6. An Overview of the Maintainability Guidelines
  3. 2. Write Short Units of Code
    1. Motivation
      1. Short Units Are Easy to Test
      2. Short Units Are Easy to Analyze
      3. Short Units Are Easy to Reuse
    2. How to Apply the Guideline
      1. When Writing a New Unit
      2. When Extending a Unit with New Functionality
      3. Using Refactoring Techniques to Apply the Guideline
    3. Common Objections to Writing Short Units
      1. Objection: Having More Units Is Bad for Performance
      2. Objection: Code Is Harder to Read When Spread Out
      3. Guideline Encourages Improper Formatting
      4. This Unit Is Impossible to Split Up
      5. There Is No Visible Advantage in Splitting Units
    4. See Also
  4. 3. Write Simple Units of Code
    1. Motivation
      1. Simple Units Are Easier to Modify
      2. Simple Units Are Easier to Test
    2. How to Apply the Guideline
      1. Dealing with Conditional Chains
      2. Dealing with Nesting
    3. Common Objections to Writing Simple Units of Code
      1. Objection: High Complexity Cannot Be Avoided
      2. Objection: Splitting Up Methods Does Not Reduce Complexity
    4. See Also
  5. 4. Write Code Once
    1. Types of Duplication
    2. Motivation
      1. Duplicated Code Is Harder to Analyze
      2. Duplicated Code Is Harder to Modify
    3. How to Apply the Guideline
      1. The Extract Superclass Refactoring Technique
    4. Common Objections to Avoiding Code Duplication
      1. Copying from Another Codebase Should Be Allowed
      2. Slight Variations, and Hence Duplication, Are Unavoidable
      3. This Code Will Never Change
      4. Duplicates of Entire Files Should Be Allowed as Backups
      5. Unit Tests Are Covering Me
      6. Duplication in String Literals Is Unavoidable and Harmless
    5. See Also
  6. 5. Keep Unit Interfaces Small
    1. Motivation
      1. Small Interfaces Are Easier to Understand and Reuse
      2. Methods with Small Interfaces Are Easier to Modify
    2. How to Apply the Guideline
    3. Common Objections to Keeping Unit Interfaces Small
      1. Objection: Parameter Objects with Large Interfaces
      2. Refactoring Large Interfaces Does Not Improve My Situation
      3. Frameworks or Libraries Prescribe Interfaces with Long Parameter Lists
    4. See Also
  7. 6. Separate Concerns in Modules
    1. Motivation
      1. Small, Loosely Coupled Modules Allow Developers to Work on Isolated Parts of the Codebase
      2. Small, Loosely Coupled Modules Ease Navigation Through the Codebase
      3. Small, Loosely Coupled Modules Prevent No-Go Areas for New Developers
    2. How to Apply the Guideline
      1. Split Classes to Separate Concerns
      2. Hide Specialized Implementations Behind Interfaces
      3. Replace Custom Code with Third-Party Libraries/Frameworks
    3. Common Objections to Separating Concerns
      1. Objection: Loose Coupling Conflicts With Reuse
      2. Objection: Java Interfaces Are Not Just for Loose Coupling
      3. Objection: High Fan-in of Utility Classes Is Unavoidable
      4. Objection: Not All Loose Coupling Solutions Increase Maintainability
  8. 7. Couple Architecture Components Loosely
    1. Motivation
      1. Low Component Dependence Allows for Isolated Maintenance
      2. Low Component Dependence Separates Maintenance Responsibilities
      3. Low Component Dependence Eases Testing
    2. How to Apply the Guideline
      1. Abstract Factory Design Pattern
    3. Common Objections to Loose Component Coupling
      1. Objection: Component Dependence Cannot Be Fixed Because the Components Are Entangled
      2. Objection: No Time to Fix
      3. Objection: Throughput Is a Requirement
    4. See Also
  9. 8. Keep Architecture Components Balanced
    1. Motivation
      1. A Good Component Balance Eases Finding and Analyzing Code
      2. A Good Component Balance Better Isolates Maintenance Effects
      3. A Good Component Balance Separates Maintenance Responsibilities
    2. How to Apply the Guideline
      1. Decide on the Right Conceptual Level for Grouping Functionality into Components
      2. Clarify the System’s Domains and Apply Those Consistently
    3. Common Objections to Balancing Components
      1. Objection: Component Imbalance Works Just Fine
      2. Objection: Entanglement Is Impairing Component Balance
    4. See Also
  10. 9. Keep Your Codebase Small
    1. Motivation
      1. A Project That Sets Out to Build a Large Codebase Is More Likely to Fail
      2. Large Codebases Are Harder to Maintain
      3. Large Systems Have Higher Defect Density
    2. How to Apply the Guideline
      1. Functional Measures
      2. Technical Measures
    3. Common Objections to Keeping the Codebase Small
      1. Objection: Reducing the Codebase Size Is Impeded by Productivity Measures
      2. Objection: Reducing the Codebase Size is Impeded by the Programming Language
      3. Objection: System Complexity Forces Code Copying
      4. Objection: Splitting the Codebase Is Impossible Because of Platform Architecture
      5. Objection: Splitting the Codebase Leads to Duplication
      6. Objection: Splitting the Codebase Is Impossible Because of Tight Coupling
  11. 10. Automate Tests
    1. Motivation
      1. Automated Testing Makes Testing Repeatable
      2. Automated Testing Makes Development Efficient
      3. Automated Testing Makes Code Predictable
      4. Tests Document the Code That Is Tested
      5. Writing Tests Make You Write Better Code
    2. How to Apply the Guideline
      1. Getting Started with jUnit Tests
      2. General Principles for Writing Good Unit Tests
      3. Measure Coverage to Determine Whether There Are Enough Tests
    3. Common Objections to Automating Tests
      1. Objection: We Still Need Manual Testing
      2. Objection: I Am Not Allowed to Write Unit Tests
      3. Objection: Why Should We Invest in Unit Tests When the Current Coverage Is Low?
    4. See Also
  12. 11. Write Clean Code
    1. Leave No Trace
    2. How to Apply the Guideline
      1. Rule 1: Leave No-Unit Level Code Smells Behind
      2. Rule 2: Leave No Bad Comments Behind
      3. Rule 3: Leave No Code in Comments Behind
      4. Rule 4: Leave No Dead Code Behind
      5. Rule 5: Leave No Long Identifiers Behind
      6. Rule 6: Leave No Magic Constants Behind
      7. Rule 7: Leave No Badly Handled Exception Behind
    3. Common Objections to Writing Clean Code
      1. Objection: Comments Are Our Documentation
      2. Objection: Exception Handling Causes Code Additions
      3. Objection: Why Only These Coding Guidelines?
  13. 12. Next Steps
    1. Turning the Guidelines into Practice
    2. Lower-Level (Unit) Guidelines Take Precedence Over Higher-Level (Component) Guidelines
    3. Remember That Every Commit Counts
    4. Development Process Best Practices Are Discussed in the Follow-Up Book
  14. A. How SIG Measures Maintainability
  15. Index

Product information

  • Title: Building Maintainable Software, Java Edition
  • Author(s): Joost Visser, Sylvan Rigal, Rob van der Leek, Pascal van Eck, Gijs Wijnholds
  • Release date: January 2016
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9781491953495