Good Code, Bad Code

Good Code, Bad Code

by Tom Long
Released August 2021
Publisher(s): Manning Publications
ISBN: 9781617298936

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

Practical techniques for writing code that is robust, reliable, and easy for team members to understand and adapt.

In Good Code, Bad Code you’ll learn how to:
  • Think about code like an effective software engineer
  • Write functions that read like well-structured sentences
  • Ensure code is reliable and bug free
  • Effectively unit test code
  • Identify code that can cause problems and improve it
  • Write code that is reusable and adaptable to new requirements
  • Improve your medium and long-term productivity
  • Save yourself and your team time

The difference between good code or bad code often comes down to how you apply the established practices of the software development community. In Good Code, Bad Code you’ll learn how to boost your productivity and effectiveness with code development insights normally only learned through careful mentorship and hundreds of code reviews.

About the Technology
Software development is a team sport. For an application to succeed, your code needs to be robust and easy for others to understand, maintain, and adapt. Whether you’re working on an enterprise team, contributing to an open source project, or bootstrapping a startup, it pays to know the difference between good code and bad code.

About the Book
Good Code, Bad Code is a clear, practical introduction to writing code that’s a snap to read, apply, and remember. With dozens of instantly-useful techniques, you’ll find coding insights that normally take years of experience to master. In this fast-paced guide, Google software engineer Tom Long teaches you a host of rules to apply, along with advice on when to break them!

What's Inside
  • Write functions that read like sentences
  • Ensure your code stays bug-free
  • How to sniff out bad code
  • Save time for yourself and your team


About the Reader
For coders early in their careers who are familiar with an object-oriented language, such as Java or C#.

About the Author
Tom Long is a software engineer at Google where he works as a tech lead. Among other tasks, he regularly mentors new software engineers in professional coding best practices.

Quotes
A wealth of knowledge to sharpen your toolset.
- Joe Ivans, California Regional MLS

Pragmatic advice and useful tips for a career in software development.
- George Thomas, Manhattan Associates

A practical, informative book designed to help developers write high-quality, effective code.
- Christopher Villanueva, Independent Consultant

Smart, well written, actionable information for creating maintainable code.
- Hawley Waldman, Consultant

Table of contents

  1. Good Code, Bad Code
  2. Copyright
  3. contents
  4. front matter
    1. preface
    2. acknowledgments
    3. about this book
      1. Who should read this book
      2. How this book is organized: A roadmap
      3. About the code
      4. liveBook discussion forum
      5. How to use the advice in this book
      6. Further reading
    4. about the author
    5. about the cover illustration
  5. Part 1 In theory
  6. 1 Code quality
    1. 1.1 How code becomes software
    2. 1.2 The goals of code quality
      1. 1.2.1 Code should work
      2. 1.2.2 Code should keep working
      3. 1.2.3 Code should be adaptable to changing requirements
      4. 1.2.4 Code should not reinvent the wheel
    3. 1.3 The pillars of code quality
      1. 1.3.1 Make code readable
      2. 1.3.2 Avoid surprises
      3. 1.3.3 Make code hard to misuse
      4. 1.3.4 Make code modular
      5. 1.3.5 Make code reusable and generalizable
      6. 1.3.6 Make code testable and test it properly
    4. 1.4 Does writing high-quality code slow us down?
    5. Summary
  7. 2 Layers of abstraction
    1. 2.1 Nulls and the pseudocode convention in this book
    2. 2.2 Why create layers of abstraction?
      1. 2.2.1 Layers of abstraction and the pillars of code quality
    3. 2.3 Layers of code
      1. 2.3.1 APIs and implementation details
      2. 2.3.2 Functions
      3. 2.3.3 Classes
      4. 2.3.4 Interfaces
      5. 2.3.5 When layers get too thin
    4. 2.4 What about microservices?
    5. Summary
  8. 3 Other engineers and code contracts
    1. 3.1 Your code and other engineers’ code
      1. 3.1.1 Things that are obvious to you are not obvious to others
      2. 3.1.2 Other engineers will inadvertently try to break your code
      3. 3.1.3 In time, you will forget about your own code
    2. 3.2 How will others figure out how to use your code?
      1. 3.2.1 Looking at the names of things
      2. 3.2.2 Looking at the data types of things
      3. 3.2.3 Reading documentation
      4. 3.2.4 Asking you in person
      5. 3.2.5 Looking at your code
    3. 3.3 Code contracts
      1. 3.3.1 Small print in contracts
      2. 3.3.2 Don’t rely too much on small print
    4. 3.4 Checks and assertions
      1. 3.4.1 Checks
      2. 3.4.2 Assertions
    5. Summary
  9. 4 Errors
    1. 4.1 Recoverability
      1. 4.1.1 Errors that can be recovered from
      2. 4.1.2 Errors that cannot be recovered from
      3. 4.1.3 Often only the caller knows if an error can be recovered from
      4. 4.1.4 Make callers aware of errors they might want to recover from
    2. 4.2 Robustness vs. failure
      1. 4.2.1 Fail fast
      2. 4.2.2 Fail loudly
      3. 4.2.3 Scope of recoverability
      4. 4.2.4 Don’t hide errors
    3. 4.3 Ways of signaling errors
      1. 4.3.1 Recap: Exceptions
      2. 4.3.2 Explicit: Checked exceptions
      3. 4.3.3 Implicit: Unchecked exceptions
      4. 4.3.4 Explicit: Nullable return type
      5. 4.3.5 Explicit: Result return type
      6. 4.3.6 Explicit: Outcome return type
      7. 4.3.7 Implicit: Promise or future
      8. 4.3.8 Implicit: Returning a magic value
    4. 4.4 Signaling errors that can’t be recovered from
    5. 4.5 Signaling errors that a caller might want to recover from
      1. 4.5.1 Arguments for using unchecked exceptions
      2. 4.5.2 Arguments for using explicit techniques
      3. 4.5.3 My opinion: Use an explicit technique
    6. 4.6 Don’t ignore compiler warnings
    7. Summary
  10. Part 2 In practice
  11. 5 Make code readable
    1. 5.1 Use descriptive names
      1. 5.1.1 Nondescriptive names make code hard to read
      2. 5.1.2 Comments are a poor substitute for descriptive names
      3. 5.1.3 Solution: Make names descriptive
    2. 5.2 Use comments appropriately
      1. 5.2.1 Redundant comments can be harmful
      2. 5.2.2 Comments are a poor substitute for readable code
      3. 5.2.3 Comments can be great for explaining why code exists
      4. 5.2.4 Comments can provide useful high-level summaries
    3. 5.3 Don’t fixate on number of lines of code
      1. 5.3.1 Avoid succinct but unreadable code
      2. 5.3.2 Solution: Make code readable, even if it requires more lines
    4. 5.4 Stick to a consistent coding style
      1. 5.4.1 An inconsistent coding style can cause confusion
      2. 5.4.2 Solution: Adopt and follow a style guide
    5. 5.5 Avoid deeply nesting code
      1. 5.5.1 Deeply nested code can be hard to read
      2. 5.5.2 Solution: Restructure to minimize nesting
      3. 5.5.3 Nesting is often a result of doing too much
      4. 5.5.4 Solution: Break code into smaller functions
    6. 5.6 Make function calls readable
      1. 5.6.1 Arguments can be hard to decipher
      2. 5.6.2 Solution: Use named arguments
      3. 5.6.3 Solution: Use descriptive types
      4. 5.6.4 Sometimes there’s no great solution
      5. 5.6.5 What about the IDE?
    7. 5.7 Avoid using unexplained values
      1. 5.7.1 Unexplained values can be confusing
      2. 5.7.2 Solution: Use a well-named constant
      3. 5.7.3 Solution: Use a well-named function
    8. 5.8 Use anonymous functions appropriately
      1. 5.8.1 Anonymous functions can be great for small things
      2. 5.8.2 Anonymous functions can be hard to read
      3. 5.8.3 Solution: Use named functions instead
      4. 5.8.4 Large anonymous functions can be problematic
      5. 5.8.5 Solution: Break large anonymous functions into named functions
    9. 5.9 Use shiny, new language features appropriately
      1. 5.9.1 New features can improve code
      2. 5.9.2 Obscure features can be confusing
      3. 5.9.3 Use the best tool for the job
    10. Summary
  12. 6 Avoid surprises
    1. 6.1 Avoid returning magic values
      1. 6.1.1 Magic values can lead to bugs
      2. 6.1.2 Solution: Return null, an optional, or an error
      3. 6.1.3 Sometimes magic values can happen accidentally
    2. 6.2 Use the null object pattern appropriately
      1. 6.2.1 Returning an empty collection can improve code
      2. 6.2.2 Returning an empty string can sometimes be problematic
      3. 6.2.3 More complicated null objects can cause surprises
      4. 6.2.4 A null object implementation can cause surprises
    3. 6.3 Avoid causing unexpected side effects
      1. 6.3.1 Side effects that are obvious and intentional are fine
      2. 6.3.2 Unexpected side effects can be problematic
      3. 6.3.3 Solution: Avoid a side effect or make it obvious
    4. 6.4 Beware of mutating input parameters
      1. 6.4.1 Mutating an input parameter can lead to bugs
      2. 6.4.2 Solution: Copy things before mutating them
    5. 6.5 Avoid writing misleading functions
      1. 6.5.1 Doing nothing when a critical input is missing can cause surprises
      2. 6.5.2 Solution: Make critical inputs required
    6. 6.6 Future-proof enum handling
      1. 6.6.1 Implicitly handling future enum values can be problematic
      2. 6.6.2 Solution: Use an exhaustive switch statement
      3. 6.6.3 Beware of the default case
      4. 6.6.4 Caveat: Relying on another project’s enum
    7. 6.7 Can’t we just solve all this with testing?
    8. Summary
  13. 7 Make code hard to misuse
    1. 7.1 Consider making things immutable
      1. 7.1.1 Mutable classes can be easy to misuse
      2. 7.1.2 Solution: Set values only at construction time
      3. 7.1.3 Solution: Use a design pattern for immutability
    2. 7.2 Consider making things deeply immutable
      1. 7.2.1 Deep mutability can lead to misuse
      2. 7.2.2 Solution: Defensively copy things
      3. 7.2.3 Solution: Use immutable data structures
    3. 7.3 Avoid overly general data types
      1. 7.3.1 Overly general types can be misused
      2. 7.3.2 Pair types are easy to misuse
      3. 7.3.3 Solution: Use a dedicated type
    4. 7.4 Dealing with time
      1. 7.4.1 Representing time with integers can be problematic
      2. 7.4.2 Solution: Use appropriate data structures for time
    5. 7.5 Have single sources of truth for data
      1. 7.5.1 Second sources of truth can lead to invalid states
      2. 7.5.2 Solution: Use primary data as the single source of truth
    6. 7.6 Have single sources of truth for logic
      1. 7.6.1 Multiple sources of truth for logic can lead to bugs
      2. 7.6.2 Solution: Have a single source of truth
    7. Summary
  14. 8 Make code modular
    1. 8.1 Consider using dependency injection
      1. 8.1.1 Hard-coded dependencies can be problematic
      2. 8.1.2 Solution: Use dependency injection
      3. 8.1.3 Design code with dependency injection in mind
    2. 8.2 Prefer depending on interfaces
      1. 8.2.1 Depending on concrete implementations limits adaptability
      2. 8.2.2 Solution: Depend on interfaces where possible
    3. 8.3 Beware of class inheritance
      1. 8.3.1 Class inheritance can be problematic
      2. 8.3.2 Solution: Use composition
      3. 8.3.3 What about genuine is-a relationships?
    4. 8.4 Classes should care about themselves
      1. 8.4.1 Caring too much about other classes can be problematic
      2. 8.4.2 Solution: Make classes care about themselves
    5. 8.5 Encapsulate related data together
      1. 8.5.1 Unencapsulated data can be difficult to handle
      2. 8.5.2 Solution: Group related data into objects or classes
    6. 8.6 Beware of leaking implementation details in return types
      1. 8.6.1 Leaking implementation details in a return type can be problematic
      2. 8.6.2 Solution: Return a type appropriate to the layer of abstraction
    7. 8.7 Beware of leaking implementation details in exceptions
      1. 8.7.1 Leaking implementation details in exceptions can be problematic
      2. 8.7.2 Solution: Make exceptions appropriate to the layer of abstraction
    8. Summary
  15. 9 Make code reusable and generalizable
    1. 9.1 Beware of assumptions
      1. 9.1.1 Assumptions can lead to bugs when code is reused
      2. 9.1.2 Solution: Avoid unnecessary assumptions
      3. 9.1.3 Solution: If an assumption is necessary, enforce it
    2. 9.2 Beware of global state
      1. 9.2.1 Global state can make reuse unsafe
      2. 9.2.2 Solution: Dependency-inject shared state
    3. 9.3 Use default return values appropriately
      1. 9.3.1 Default return values in low-level code can harm reusability
      2. 9.3.2 Solution: Provide defaults in higher level code
    4. 9.4 Keep function parameters focused
      1. 9.4.1 A function that takes more than it needs can be hard to reuse
      2. 9.4.2 Solution: Make functions take only what they need
    5. 9.5 Consider using generics
      1. 9.5.1 Depending on a specific type limits generalizability
      2. 9.5.2 Solution: Use generics
    6. Summary
  16. Part 3 Unit testing
  17. 10 Unit testing principles
    1. 10.1 Unit testing primer
    2. 10.2 What makes a good unit test?
      1. 10.2.1 Accurately detects breakages
      2. 10.2.2 Agnostic to implementation details
      3. 10.2.3 Well-explained failures
      4. 10.2.4 Understandable test code
      5. 10.2.5 Easy and quick to run
    3. 10.3 Focus on the public API but don’t ignore important behaviors
      1. 10.3.1 Important behaviors might be outside the public API
    4. 10.4 Test doubles
      1. 10.4.1 Reasons for using a test double
      2. 10.4.2 Mocks
      3. 10.4.3 Stubs
      4. 10.4.4 Mocks and stubs can be problematic
      5. 10.4.5 Fakes
      6. 10.4.6 Schools of thought on mocking
    5. 10.5 Pick and choose from testing philosophies
    6. Summary
  18. 11 Unit testing practices
    1. 11.1 Test behaviors not just functions
      1. 11.1.1 One test case per function is often inadequate
      2. 11.1.2 Solution: Concentrate on testing each behavior
    2. 11.2 Avoid making things visible just for testing
      1. 11.2.1 Testing private functions is often a bad idea
      2. 11.2.2 Solution: Prefer testing via the public API
      3. 11.2.3 Solution: Split the code into smaller units
    3. 11.3 Test one behavior at a time
      1. 11.3.1 Testing multiple behaviors at once can lead to poor tests
      2. 11.3.2 Solution: Test each behavior in its own test case
      3. 11.3.3 Parameterized tests
    4. 11.4 Use shared test setup appropriately
      1. 11.4.1 Shared state can be problematic
      2. 11.4.2 Solution: Avoid sharing state or reset it
      3. 11.4.3 Shared configuration can be problematic
      4. 11.4.4 Solution: Define important configuration within test cases
      5. 11.4.5 When shared configuration is appropriate
    5. 11.5 Use appropriate assertion matchers
      1. 11.5.1 Inappropriate matchers can lead to poorly explained failures
      2. 11.5.2 Solution: Use an appropriate matcher
    6. 11.6 Use dependency injection to aid testability
      1. 11.6.1 Hard-coded dependencies can make code impossible to test
      2. 11.6.2 Solution: Use dependency injection
    7. 11.7 Some final words on testing
    8. Summary
  19. Appendix A. Chocolate brownie recipe
  20. Appendix B. Null safety and optionals
    1. B.1 Using null safety
      1. B.1.1 Checking for nulls
    2. B.2 Using optional
  21. Appendix C. Extra code examples
    1. C.1 The builder pattern
  22. index

Product information

  • Title: Good Code, Bad Code
  • Author(s): Tom Long
  • Release date: August 2021
  • Publisher(s): Manning Publications
  • ISBN: 9781617298936