book

Good Code, Bad Code

by Tom Long

August 2021

Intermediate to advanced

376 pages

11h 2m

English

Manning Publications

Read now

Unlock full access

prefaceacknowledgmentsabout this bookWho should read this bookHow this book is organized: A roadmapAbout the codeliveBook discussion forumHow to use the advice in this bookFurther readingabout the authorabout the cover illustration
1.1 How code becomes software1.2 The goals of code quality1.2.1 Code should work1.2.2 Code should keep working1.2.3 Code should be adaptable to changing requirements1.2.4 Code should not reinvent the wheel1.3 The pillars of code quality1.3.1 Make code readable1.3.2 Avoid surprises1.3.3 Make code hard to misuse1.3.4 Make code modular1.3.5 Make code reusable and generalizable1.3.6 Make code testable and test it properly1.4 Does writing high-quality code slow us down?Summary
2.1 Nulls and the pseudocode convention in this book2.2 Why create layers of abstraction?2.2.1 Layers of abstraction and the pillars of code quality2.3 Layers of code2.3.1 APIs and implementation details2.3.2 Functions2.3.3 Classes2.3.4 Interfaces2.3.5 When layers get too thin2.4 What about microservices?Summary
3.1 Your code and other engineers’ code3.1.1 Things that are obvious to you are not obvious to others3.1.2 Other engineers will inadvertently try to break your code3.1.3 In time, you will forget about your own code3.2 How will others figure out how to use your code?3.2.1 Looking at the names of things3.2.2 Looking at the data types of things3.2.3 Reading documentation3.2.4 Asking you in person3.2.5 Looking at your code3.3 Code contracts3.3.1 Small print in contracts3.3.2 Don’t rely too much on small print3.4 Checks and assertions3.4.1 Checks3.4.2 AssertionsSummary
4.1 Recoverability4.1.1 Errors that can be recovered from4.1.2 Errors that cannot be recovered from4.1.3 Often only the caller knows if an error can be recovered from4.1.4 Make callers aware of errors they might want to recover from4.2 Robustness vs. failure4.2.1 Fail fast4.2.2 Fail loudly4.2.3 Scope of recoverability4.2.4 Don’t hide errors4.3 Ways of signaling errors4.3.1 Recap: Exceptions4.3.2 Explicit: Checked exceptions4.3.3 Implicit: Unchecked exceptions4.3.4 Explicit: Nullable return type4.3.5 Explicit: Result return type4.3.6 Explicit: Outcome return type4.3.7 Implicit: Promise or future4.3.8 Implicit: Returning a magic value4.4 Signaling errors that can’t be recovered from4.5 Signaling errors that a caller might want to recover from4.5.1 Arguments for using unchecked exceptions4.5.2 Arguments for using explicit techniques4.5.3 My opinion: Use an explicit technique4.6 Don’t ignore compiler warningsSummary

5.1 Use descriptive names5.1.1 Nondescriptive names make code hard to read5.1.2 Comments are a poor substitute for descriptive names5.1.3 Solution: Make names descriptive5.2 Use comments appropriately5.2.1 Redundant comments can be harmful5.2.2 Comments are a poor substitute for readable code5.2.3 Comments can be great for explaining why code exists5.2.4 Comments can provide useful high-level summaries5.3 Don’t fixate on number of lines of code5.3.1 Avoid succinct but unreadable code5.3.2 Solution: Make code readable, even if it requires more lines5.4 Stick to a consistent coding style5.4.1 An inconsistent coding style can cause confusion5.4.2 Solution: Adopt and follow a style guide5.5 Avoid deeply nesting code5.5.1 Deeply nested code can be hard to read5.5.2 Solution: Restructure to minimize nesting5.5.3 Nesting is often a result of doing too much5.5.4 Solution: Break code into smaller functions5.6 Make function calls readable5.6.1 Arguments can be hard to decipher5.6.2 Solution: Use named arguments5.6.3 Solution: Use descriptive types5.6.4 Sometimes there’s no great solution5.6.5 What about the IDE?5.7 Avoid using unexplained values5.7.1 Unexplained values can be confusing5.7.2 Solution: Use a well-named constant5.7.3 Solution: Use a well-named function5.8 Use anonymous functions appropriately5.8.1 Anonymous functions can be great for small things5.8.2 Anonymous functions can be hard to read5.8.3 Solution: Use named functions instead5.8.4 Large anonymous functions can be problematic5.8.5 Solution: Break large anonymous functions into named functions5.9 Use shiny, new language features appropriately5.9.1 New features can improve code5.9.2 Obscure features can be confusing5.9.3 Use the best tool for the jobSummary
6.1 Avoid returning magic values6.1.1 Magic values can lead to bugs6.1.2 Solution: Return null, an optional, or an error6.1.3 Sometimes magic values can happen accidentally6.2 Use the null object pattern appropriately6.2.1 Returning an empty collection can improve code6.2.2 Returning an empty string can sometimes be problematic6.2.3 More complicated null objects can cause surprises6.2.4 A null object implementation can cause surprises6.3 Avoid causing unexpected side effects6.3.1 Side effects that are obvious and intentional are fine6.3.2 Unexpected side effects can be problematic6.3.3 Solution: Avoid a side effect or make it obvious6.4 Beware of mutating input parameters6.4.1 Mutating an input parameter can lead to bugs6.4.2 Solution: Copy things before mutating them6.5 Avoid writing misleading functions6.5.1 Doing nothing when a critical input is missing can cause surprises6.5.2 Solution: Make critical inputs required6.6 Future-proof enum handling6.6.1 Implicitly handling future enum values can be problematic6.6.2 Solution: Use an exhaustive switch statement6.6.3 Beware of the default case6.6.4 Caveat: Relying on another project’s enum6.7 Can’t we just solve all this with testing?Summary
7.1 Consider making things immutable7.1.1 Mutable classes can be easy to misuse7.1.2 Solution: Set values only at construction time7.1.3 Solution: Use a design pattern for immutability7.2 Consider making things deeply immutable7.2.1 Deep mutability can lead to misuse7.2.2 Solution: Defensively copy things7.2.3 Solution: Use immutable data structures7.3 Avoid overly general data types7.3.1 Overly general types can be misused7.3.2 Pair types are easy to misuse7.3.3 Solution: Use a dedicated type7.4 Dealing with time7.4.1 Representing time with integers can be problematic7.4.2 Solution: Use appropriate data structures for time7.5 Have single sources of truth for data7.5.1 Second sources of truth can lead to invalid states7.5.2 Solution: Use primary data as the single source of truth7.6 Have single sources of truth for logic7.6.1 Multiple sources of truth for logic can lead to bugs7.6.2 Solution: Have a single source of truthSummary
8.1 Consider using dependency injection8.1.1 Hard-coded dependencies can be problematic8.1.2 Solution: Use dependency injection8.1.3 Design code with dependency injection in mind8.2 Prefer depending on interfaces8.2.1 Depending on concrete implementations limits adaptability8.2.2 Solution: Depend on interfaces where possible8.3 Beware of class inheritance8.3.1 Class inheritance can be problematic8.3.2 Solution: Use composition8.3.3 What about genuine is-a relationships?8.4 Classes should care about themselves8.4.1 Caring too much about other classes can be problematic8.4.2 Solution: Make classes care about themselves8.5 Encapsulate related data together8.5.1 Unencapsulated data can be difficult to handle8.5.2 Solution: Group related data into objects or classes8.6 Beware of leaking implementation details in return types8.6.1 Leaking implementation details in a return type can be problematic8.6.2 Solution: Return a type appropriate to the layer of abstraction8.7 Beware of leaking implementation details in exceptions8.7.1 Leaking implementation details in exceptions can be problematic8.7.2 Solution: Make exceptions appropriate to the layer of abstractionSummary
9.1 Beware of assumptions9.1.1 Assumptions can lead to bugs when code is reused9.1.2 Solution: Avoid unnecessary assumptions9.1.3 Solution: If an assumption is necessary, enforce it9.2 Beware of global state9.2.1 Global state can make reuse unsafe9.2.2 Solution: Dependency-inject shared state9.3 Use default return values appropriately9.3.1 Default return values in low-level code can harm reusability9.3.2 Solution: Provide defaults in higher level code9.4 Keep function parameters focused9.4.1 A function that takes more than it needs can be hard to reuse9.4.2 Solution: Make functions take only what they need9.5 Consider using generics9.5.1 Depending on a specific type limits generalizability9.5.2 Solution: Use genericsSummary
10.1 Unit testing primer10.2 What makes a good unit test?10.2.1 Accurately detects breakages10.2.2 Agnostic to implementation details10.2.3 Well-explained failures10.2.4 Understandable test code10.2.5 Easy and quick to run10.3 Focus on the public API but don’t ignore important behaviors10.3.1 Important behaviors might be outside the public API10.4 Test doubles10.4.1 Reasons for using a test double10.4.2 Mocks10.4.3 Stubs10.4.4 Mocks and stubs can be problematic10.4.5 Fakes10.4.6 Schools of thought on mocking10.5 Pick and choose from testing philosophiesSummary
11.1 Test behaviors not just functions11.1.1 One test case per function is often inadequate11.1.2 Solution: Concentrate on testing each behavior11.2 Avoid making things visible just for testing11.2.1 Testing private functions is often a bad idea11.2.2 Solution: Prefer testing via the public API11.2.3 Solution: Split the code into smaller units11.3 Test one behavior at a time11.3.1 Testing multiple behaviors at once can lead to poor tests11.3.2 Solution: Test each behavior in its own test case11.3.3 Parameterized tests11.4 Use shared test setup appropriately11.4.1 Shared state can be problematic11.4.2 Solution: Avoid sharing state or reset it11.4.3 Shared configuration can be problematic11.4.4 Solution: Define important configuration within test cases11.4.5 When shared configuration is appropriate11.5 Use appropriate assertion matchers11.5.1 Inappropriate matchers can lead to poorly explained failures11.5.2 Solution: Use an appropriate matcher11.6 Use dependency injection to aid testability11.6.1 Hard-coded dependencies can make code impossible to test11.6.2 Solution: Use dependency injection11.7 Some final words on testingSummary
B.1 Using null safetyB.1.1 Checking for nullsB.2 Using optional
C.1 The builder pattern

Content preview from Good Code, Bad Code

5 Make code readable

This chapter covers

Techniques for making code self-explanatory
Ensuring that details within the code are clear to others
Using language features for the right reasons

Readability is inherently a subjective thing, and it’s therefore hard to put a solid definition on exactly what it means. The essence of readability is ensuring that engineers can quickly and accurately understand what some code does. Actually achieving this often requires being empathetic and trying to imagine how things might be confusing or open to misinterpretation when seen from someone else’s point of view.

This chapter should provide a solid grounding in some of the most common and effective techniques for making code more readable. It’s worth remembering, ...