Google Testing Blog

Set Safe Defaults for Flags

2026-03-03T06:47:00.000-08:00

This article was adapted from a Google Tech on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Zhe Lu

We all make mistakes. But big mistakes can cause big headaches! Suppose you're writing a utility to update production data for a launch. Before making changes to production data, you want to perform a dry run to validate the expected changes. In your excitement, you forget to include the --dry_run flag in your command:

$ /scripts/credit_accounts --amount=USD10 # Oops, I forgot to include --dry_run

You realize your mistake too late. Safe flag defaults can prevent a simple mistake from turning into a major outage:

Flag has unsafe default:

cliArgs.addBoolFlag(name="dry_run", default=False, help="If set, print change summary, but do NOT change data.")

Flag has safe default:

cliArgs.addBoolFlag(name="dry_run", default=True, help="If set, print change summary, but do NOT change data.")

Safety depends on context: When defining flags, choose the default that minimizes the cost of potential mistakes. This might involve defaulting to a "dry" run, asking for user confirmation before irreversible actions, requiring a confirmation flag on the command line, or other strategies. If you’re writing documentation that contains commands, always set values to minimize the damage if run blindly:

Flag in documentation has unsafe default:

## How to commit changes

Use this command to commit changes. Use --dry_run to test and compute and report changes.

```shell

/scripts/credit_accounts --amount=[value] --filter=[conditions]

```

Flag in documentation has safe default:

## How to commit changes

Use this command to compute and report changes. Use --nodry_run to commit the changes.

```shell

/scripts/credit_accounts --amount=[value] --filter=[conditions]

```

Similarly, consider requiring that environment-specific flags (e.g., backend addresses and output folders) be explicitly set. In this situation, unspecified environment flags will crash your program, instead of potentially mixing configuration across environments.

Simplify Your Code: Functional Core, Imperative Shell

2025-10-20T06:53:00.000-07:00

This article was adapted from a Google Tech on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Arham Jain

Is your code a tangled mess of business logic and side effects? Mixing database calls, network requests, and other external interactions directly with your core logic can lead to code that’s difficult to test, reuse, and understand. Instead, consider writing a functional core that’s called from an imperative shell.

Separating your code into functional cores and imperative shells makes it more testable, maintainable, and adaptable. The core logic can be tested in isolation, and the imperative shell can be swapped out or modified as needed. Here’s some messy example code that mixes logic and side effects to send expiration notification emails to users:

// Bad: Logic and side effects are mixed

function sendUserExpiryEmail(): void {

for (const user of db.getUsers()) {

if (user.subscriptionEndDate > Date.now()) continue;

if (user.isFreeTrial) continue;

email.send(user.email, "Your account has expired " + user.name + “.”);

}

A functional core should contain pure, testable business logic, which is free of side effects (such as I/O or external state mutation). It operates only on the data it is given.

An imperative shell is responsible for side effects, like database calls and sending emails. It uses the functions in your functional core to perform the business logic.

Rewriting the above code to follow the functional core / imperative shell pattern might look like:

Functional core

function getExpiredUsers(users: User[], cutoff: Date): User[] {

return users.filter(user => user.subscriptionEndDate <= cutoff && !user.isFreeTrial);

}

function generateExpiryEmails(users: User[]): Array<[string, string]> {

return users.map(user =>

([user.email, “Your account has expired “ + user.name + “.”])

);

}

Imperative shell

email.bulkSend(generateExpiryEmails(getExpiredUsers(db.getUsers(), Date.now())));

Now that the code is following this pattern, adding a feature to send a new type of email is as simple as writing a new pure function and reusing getExpiredUsers:

// Sending a reminder email to users

function generateReminderEmails(users: User[], cutoff: Date): Array<[string, string]> {...}

const fiveDaysFromNow = ...

email.bulkSend(generateReminderEmails(getExpiredUsers(db.getUsers(), fiveDaysFromNow)));

Learn more in Gary Bernhardt’s original talk about functional core, imperative shell.

Sort Lines in Source Code

2025-09-15T06:45:00.000-07:00

This article was adapted from a Google Tech on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Kyle Freeman

Imagine you're adding a two-player mode to a game. When testing the feature, you launch the game but don't see the option to add a second player. The configuration looks correct; you enabled two-player mode on the last line!

So what happened? Can you spot the bug in the following example?

allow_warping: false

enable_two_players: false

show_end_credits: true

enable_frost_band: false

enable_two_players: true

Using keep-sorted (github.com/google/keep-sorted) to sort lines makes the error easy to spot: the flag enable_two_players is set twice, with different values:

# keep-sorted start

allow_warping: false

enable_frost_band: false

enable_two_players: false

enable_two_players: true

show_end_credits: true

# keep-sorted end

Sorted lists and lines of code are easier to read and maintain, and can help prevent bugs. To use keep-sorted in your source code, config, and text files, install keep-sorted and then follow these instructions:

Add keep-sorted start and keep-sorted end comments in your file, surrounding the lines you want to sort.
Run keep-sorted: keep-sorted [file1] [file2] ...
(Optional) Add keep-sorted to your pre-commit so it runs automatically on git commit

You can add options to override default behavior. For example, you can ignore case, sort numerically, order by prefixes, and even sort by regular expressions:

bosses := []int{

// keep-sorted start by_regex=//.*

111213, // Aethon Annie

52816, // Blazing Benny

711, // Daisy Dragon

1003, // Kenzie Kraken

// keep-sorted end

}

Remember: before sorting, ensure the original order isn't intentional. For example, order can be critical when loading dependencies.

Arrange Your Code to Communicate Data Flow

2025-01-07T05:59:00.000-08:00

This article was adapted from a Google Tech on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Sebastian Dörner

We often read code linearly, from one line to the next. To make code easier to understand and to reduce cognitive load for your readers, make sure that adjacent lines of code are coherent. One way to achieve this is to order your lines of code to match the data flow inside your method:

fun getSandwich(

bread: Bread, pasture: Pasture

): Sandwich {

// This alternates between milk-

// bread-related code.

val cow = pasture.getCow()

val slicedBread = bread.slice()

val milk = cow.getMilk()

val toast = toastBread(slicedBread)

val cheese = makeCheese(milk)

return Sandwich(cheese, toast)

}

fun getSandwich(

bread: Bread, pasture: Pasture

): Sandwich {

// Linear flow from cow to milk

// to cheese.

val cow = pasture.getCow()

val milk = cow.getMilk()

val cheese = makeCheese(milk)

// Linear flow from bread to slicedBread

// to toast.

val slicedBread = bread.slice()

val toast = toastBread(slicedBread)

return Sandwich(cheese, toast)

}

To visually emphasize the grouping of related lines, you can add a blank line between each code block.

Often you can further improve readability by extracting a method, e.g., by extracting the first 3 lines of the function on the above right into a getCheese method. However, in some scenarios, extracting a method isn’t possible or helpful, e.g., if data is used a second time for logging. If you order the lines to match the data flow, you can still increase code clarity:

fun getSandwich(bread: Bread, pasture: Pasture): Sandwich {

// Both milk and cheese are used below, so this can’t easily be extracted into

// a method.

val cow = pasture.getCow()

val milk = cow.getMilk()

reportFatContentToStreamz(cow.age, milk)

val cheese = makeCheese(milk)

val slicedBread = bread.slice()

val toast = toastBread(slicedBread)

logWarningIfAnyExpired(bread, toast, milk, cheese)

return Sandwich(cheese, toast)

}

It isn’t always possible to group variables perfectly if you have more complicated data flows, but even incremental changes in this direction improve the readability of your code. A good starting point is to declare your variables as close to the first use as possible.

Tech on the Toilet: Driving Software Excellence, One Bathroom Break at a Time

2024-12-03T05:34:00.001-08:00

By Kanu Tewary and Andrew Trenk

Tech on the Toilet (TotT) is a weekly one-page publication about software development that is posted in bathrooms in Google offices worldwide. At Google, TotT is a trusted source for high quality technical content and software engineering best practices. TotT episodes relevant outside Google are posted to this blog.

We have been posting TotT to this blog since 2007. We're excited to announce that Testing on the Toilet has been renamed Tech on the Toilet. TotT originally covered only software testing topics, but for many years has been covering any topics relevant to software development, such as coding practices, machine learning, web development, and more.

A Cultural Institution

TotT is a grassroots effort with a mission to deliver easily-digestable one-pagers on software development to engineers in the most unexpected of places: bathroom stalls! But TotT is more than just bathroom reading -- it's a movement. Driven by a team of 20-percent volunteers, TotT empowers Google employees to learn and grow, fostering a culture of excellence within the Google engineering community.

Photos of TotT posted in bathroom stalls at Google.

Anyone at Google can author a TotT episode (regardless of tenure or seniority). Each episode is carefully curated and edited to provide concise, actionable, authoritative information about software best practices and developer tools. After an episode is published, it is posted to Google bathrooms around the world, and is also available to read online internally at Google. TotT episodes often become a canonical source for helping far-flung teams standardize their software development tools and practices.

Because Every Superhero Has An Origin Story

TotT began as a bottom-up approach to drive a culture change. The year was 2006 and Google was experiencing rapid growth and huge challenges: there were many costly bugs and rolled-back releases. A small group of engineers, members of the so-called Testing Grouplet, passionate about testing, brainstormed about how to instill a culture of software testing at Google. In a moment of levity, someone suggested posting flyers in restrooms (since people have time to read there, clearly!). The Testing Grouplet named their new publication Testing on the Toilet. TotT’s red lightbub, green lightbulb logo–displayed at the top of the page of each printed flyer–was adapted from the Testing Grouplet’s logo.

The TotT logo.

The first TotT episode, a simple code example with a suggested improvement, was written by an engineer at Google headquarters in Mountain View, and posted by a volunteer in Google bathrooms in London. Soon other engineers wrote episodes, and an army of volunteers started posting those episodes at their sites. Hundreds of engineers started encountering TotT episodes.

The initial response was a mix of surprise and intrigue, with some engineers even expressing outrage at the "violation" of their bathroom sanctuary. However, the majority of feedback was positive, with many appreciating the readily accessible knowledge. Learn more about the history of TotT in this blog post by one of the original members of the Testing Grouplet.

Trusted, Concise, Actionable

TotT has become an authoritative source for software development best practices at Google. Many episodes, like the following popular episodes at Google, are cited hundreds of times in code reviews and other internal documents:

A 2019 research paper presented at the International Conference of Software Engineering even analyzed the impact of TotT episodes on the adoption of internal tools and infrastructure, demonstrating its effectiveness in driving positive change.

TotT has inspired various other publications at Google, like Learning on the Loo: non-technical articles to improve efficiency, reduce stress and improve work satisfaction. Other companies have been inspired to create their own bathroom publications, thanks to TotT. So the next time you find yourself reading a TotT episode, take a moment to appreciate its humble bathroom beginnings. After all, where better to ponder the mysteries of the code than in a place of quiet contemplation?

SMURF: Beyond the Test Pyramid

2024-10-15T05:22:00.000-07:00

This article was adapted from a Google Testing on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Adam Bender

The test pyramid is the canonical heuristic for guiding test suite evolution. It conveys a simple message - prefer more unit tests than integration tests, and prefer more integration tests than end-to-end tests.

While useful, the test pyramid lacks the details you need as your test suite grows and you face challenging trade-offs. To scale your test suite, go beyond the test pyramid.

The SMURF mnemonic is an easy way to remember the tradeoffs to consider when balancing your test suite:

Speed: Unit tests are faster than other test types and can be run more often—you’ll catch problems sooner.
Maintainability: The aggregated cost of debugging and maintaining tests (of all types) adds up quickly. A larger system under test has more code, and thus greater exposure to dependency churn and requirement drift which, in turn, creates more maintenance work.
Utilization: Tests that use fewer resources (memory, disk, CPU) cost less to run. A good test suite optimizes resource utilization so that it does not grow super-linearly with the number of tests. Unit tests usually have better utilization characteristics, often because they use test doubles or only involve limited parts of a system.
Reliability: Reliable tests only fail when an actual problem has been discovered. Sorting through flaky tests for problems wastes developer time and costs resources in rerunning the tests. As the size of a system and its corresponding tests grow, non-determinism (and thus, flakiness) creeps in, and your test suite is more likely to become unreliable.
Fidelity: High-fidelity tests come closer to approximating real operating conditions (e.g., real databases or traffic loads) and better predict the behavior of our production systems. Integration and end-to-end tests can better reflect realistic conditions, while unit tests have to simulate the environment, which can lead to drift between test expectations and reality.

A radar chart of Test Type vs. Test Property (i.e. SMURF). Farther from center is better.

In many cases, the relationships between the SMURF dimensions are in tension: improving one dimension can affect the others. However, if you can improve one or more dimensions of a test without harming the others, then you should do so. When thinking about the types of your tests (unit, integration, end-to-end), your choices have meaningful implications for your test suite’s cost and the value it provides.

Write Change-Resilient Code With Domain Objects

2024-09-04T05:56:00.000-07:00

This is another post in our Code Health series. A version of this post originally appeared in Google bathrooms worldwide as a Google Testing on the Toilet episode. You can download a printer-friendly version to display in your office.

By Amy Fu

Although a product's requirements can change often, its fundamental ideas usually change slowly. This leads to an interesting insight: if we write code that matches the fundamental ideas of the product, it will be more likely to survive future product changes.

Domain objects are building blocks (such as classes and interfaces) in our code that match the fundamental ideas of the product. Instead of writing code to match the desired behavior for the product's requirements ("configure text to be white"), we match the underlying idea ("text color settings").

For example, imagine you’re part of the gPizza team, which sells tasty, fresh pizzas to feed hungry Googlers. Due to popular demand, your team has decided to add a delivery service.

Without domain objects, the quickest path to pizza delivery is to simply create a deliverPizza method:

public class DeliveryService {

public void deliverPizza(List<Pizza> pizzas) { ... }

}

Although this works well at first, what happens if gPizza expands its offerings to other foods?
You could add a new method:

public void deliverWithDrinks(List<Pizza> pizzas, List<Drink> drinks) { ... }

But as your list of requirements grows (snacks, sweets, etc.), you’ll be stuck adding more and more methods. How can you change your initial implementation to avoid this continued maintenance burden?

You could add a domain object that models the product's ideas, instead of its requirements:

A use case is a specific behavior that helps the product satisfy its business requirements.
(In this case, "Deliver pizzas so we make more money".)
A domain object represents a common idea that is shared by several similar use cases.

To identify the appropriate domain object, ask yourself:

What related use cases does the product support, and what do we plan to support in future?

A: gPizza wants to deliver pizzas now, and eventually other products such as drinks and snacks.

What common idea do these use cases share?

A: gPizza wants to send the customer the food they ordered.

What is a domain object we can use to represent this common idea?

A: The domain object is a food order. We can encapsulate the use cases in a FoodOrder class.

Domain objects can be a useful generalization - but avoid choosing objects that are too generic, since there is a tradeoff between improved maintainability and more complex, ambiguous code. Generally, aim to support only planned use cases - not all possible use cases (see YAGNI principles).

// GOOD: It's clear what we're delivering.

public void deliver(FoodOrder order) {}

// BAD: Don't support furniture delivery.

public void deliver(DeliveryList items) {}

Learn more about domain objects and the more advanced topic of domain-driven design in the book Domain-Driven Design by Eric Evans.

Less Is More: Principles for Simple Comments

2024-08-21T05:38:00.000-07:00

By David Bendory

Simplicity is the ultimate sophistication. — Leonardo da Vinci

You’re staring at a wall of code resembling a Gordian knot of Klingon. What’s making it worse? A sea of code comments so long that you’d need a bathroom break just to read them all! Let’s fix that.

Adopt the mindset of someone unfamiliar with the project to ensure simplicity. One approach is to separate the process of writing your comments from reviewing them; proofreading your comments without code context in mind helps ensure they are clear and concise for future readers.

Use self-contained comments to clearly convey intent without relying on the surrounding code for context. If you need to read the code to understand the comment, you’ve got it backwards!

Not self-contained; requires reading the code

Suggested alternative

// Respond to flashing lights in // rearview mirror.

// Pull over for police and/or yield to

// emergency vehicles.

while flashing_lights_in_rearview_mirror() {

if !move_to_slower_lane() { stop_on_shoulder(); }

}

Include only essential information in the comments and leverage external references to reduce cognitive load on the reader. For comments suggesting improvements, links to relevant bugs or docs keep comments concise while providing a path for follow-up. Note that linked docs may be inaccessible, so use judgment in deciding how much context to include directly in the comments.

Too much potential improvement in the comment

Suggested alternative

// The local bus offers good average- // case performance. Consider using // the subway which may be faster

// depending on factors like time of // day, weather, etc.

// TODO: Consider various factors to // present the best transit option.

// See issuetracker.fake/bus-vs-subway

commute_by_local_bus();

Avoid extensive implementation details in function-level comments. When implementations change, such details often result in outdated comments. Instead, describe the public API contract, focusing on what the function does.

Too much implementation detail

Suggested alternative

// For high-traffic intersections // prone to accidents, pass through // the intersection and make 3 right // turns, which is equivalent to // turning left.

// Perform a safe left turn at a

// high-traffic intersection.

// See discussion in

// dangerous-left-turns.fake/about.

fn safe_turn_left() {

go_straight();

for i in 0..3 {

turn_right();

}

In Praise of Small Pull Requests

2024-07-16T06:00:00.000-07:00

By Elliotte Rusty Harold

Note: A “pull request” refers to one self-contained change that has been submitted to version control or which is undergoing code review. At Google, this is referred to as a“CL”, which is short for “changelist”.

Prefer small, focused pull requests that do exactly one thing each. Why? Several reasons:

Small pull requests are easier to review. A mistake in a focused pull request is more obvious. In a 40 file pull request that does several things, would you notice that one if statement had reversed the logic it should have and was using true instead of false? By contrast, if that if block and its test were the only things that changed in a pull request, you’d be a lot more likely to catch the error.
Small pull requests can be reviewed quickly. A reviewer can often respond quickly by slipping small reviews in between other tasks. Larger pull requests are a big task by themselves, often waiting until the reviewer has a significant chunk of time.
If something does go wrong and your continuous build breaks on a small pull request, the small size makes it much easier to figure out exactly where the mistake is. They are also easier to rollback if something goes wrong.
By virtue of their size, small pull requests are less likely to conflict with other developers’ work. Merge conflicts are less frequent and easier to resolve.
If you’ve made a critical error, it saves a lot of work when the reviewer can point this out after you’ve only gone a little way down the wrong path. Better to find out after an hour than after several weeks.
Pull request descriptions are more accurate when pull requests are focused on one task. The revision history becomes easier to read.
Small pull requests can lead to increased code coverage because it’s easier to make sure each individual pull request is completely tested.

Small pull requests are not always possible. In particular:

Frequent pull requests require reviewers to respond quickly to code review requests. If it takes multiple hours to get a pull request reviewed, developers spend more time blocked. Small pull requests often work better when reviewers are co-located (ideally within Nerf gun range for gentle reminders).
Some features cannot safely be committed in partial states. If this is a concern, try to put the new feature behind a flag.
Refactorings such as changing an argument type in a public method may require modifying many dozens of files at once.

Nonetheless, even if a pull request can’t be small, it can still be focused, e.g., fixing one bug, adding one feature or UI element, or refactoring one method.

Don't DRY Your Code Prematurely

2024-05-28T07:20:00.000-07:00

By Dan Maksimovich

Many of us have been told the virtues of “Don’t Repeat Yourself” or DRY. Pause and consider: Is the duplication truly redundant or will the functionality need to evolve independently over time? Applying DRY principles too rigidly leads to premature abstractions that make future changes more complex than necessary.

Consider carefully if code is truly redundant or just superficially similar. While functions or classes may look the same, they may also serve different contexts and business requirements that evolve differently over time. Think about how the functions’ purpose holds with time, not just about making the code shorter. When designing abstractions, do not prematurely couple behaviors that may evolve separately in the longer term.

When does introducing an abstraction harm our code? Let’s consider the following code:

# Premature DRY abstraction assuming # uniform rules, limiting entity-

# specific changes.

class DeadlineSetter:

def __init__(self, entity_type):

self.entity_type = entity_type

def set_deadline(self, deadline):

if deadline <= datetime.now():

raise ValueError(

“Date must be in the future”)

task = DeadlineSetter(“task”)

task.set_deadline(

datetime(2024, 3, 12))

payment = DeadlineSetter(“payment”)

payment.set_deadline(

datetime(2024, 3, 18))

# Repetitive but allows for clear,

# entity-specific logic and future

# changes.

def set_task_deadline(task_deadline):

if task_deadline <= datetime.now():

raise ValueError(

“Date must be in the future”)

def set_payment_deadline( payment_deadline):

if payment_deadline <= datetime.now():

raise ValueError(

“Date must be in the future”)

set_task_deadline(

datetime(2024, 3, 12))

set_payment_deadline(

datetime(2024, 3, 18))

The approach on the right seems to violate the DRY principle since the ValueError checks are coincidentally the same. However, tasks and payments represent distinct concepts with potentially diverging logic. If payment date later required a new validation, you could easily add it to the right-hand code; adding it to the left-hand code is much more invasive.

When in doubt, keep behaviors separate until enough common patterns emerge over time that justify the coupling. On a small scale, managing duplication can be simpler than resolving a premature abstraction’s complexity. In early stages of development, tolerate a little duplication and wait to abstract.

Future requirements are often unpredictable. Think about the “You Aren’t Gonna Need It” or YAGNI principle. Either the duplication will prove to be a nonissue, or with time, it will clearly indicate the need for a well-considered abstraction.

Avoid the Long Parameter List

2024-05-20T06:42:00.000-07:00

By Gene Volovich

Have you seen code like this?

void transform(String fileIn, String fileOut, String separatorIn, String separatorOut);

This seems simple enough, but it can be difficult to remember the parameter ordering. It gets worse if you add more parameters (e.g., to specify the encoding, or to email the resulting file):

void transform(String fileIn, String fileOut, String separatorIn, String separatorOut,

String encoding, String mailTo, String mailSubject, String mailTemplate);

To make the change, will you add another (overloaded) transform method? Or add more parameters to the existing method, and update every single call to transform? Neither seems satisfactory.

One solution is to encapsulate groups of the parameters into meaningful objects. The CsvFile class used here is a “value object” — simply a holder for the data.

class CsvFile {

CsvFile(String filename, String separator, String encoding) { ... }

String filename() { return filename; }

String separator() { return separator; }

String encoding() { return encoding; }

} // ... and do the same for the EmailMessage class

void transform(CsvFile src, CsvFile target, EmailMessage resultMsg) { ... }

How to define a value object varies by language. For example, in Java, you can use a record class, which is available in Java 16+ (for older versions of Java, you can use AutoValue to generate code for the value object); in Kotlin, you can use a data class; in C++, you can use an option struct.

Using a value object this way may still result in a long parameter list when instantiating it. Solutions for this vary by language. For example, in Python, you can use keyword arguments and default parameter values to shorten the parameter list; in Java, one option is to use the Builder pattern, which lets you call a separate function to set each field, and allows you to skip setting fields that have default values.

CsvFile src = CsvFile.builder().setFilename("a.txt").setSeparator(":").build();

CsvFile target = CsvFile.builder().setFilename("b.txt").setEncoding(UTF_8).build();

EmailMessage msg =

EmailMessage.builder().setMailTo(rcpt).setMailTemplate("template").build();

transform(src, target, msg);

Always try to group data that belongs together and break up long, complicated parameter lists. The result will be code that is easier to read and maintain, and harder to make mistakes with.

Test Failures Should Be Actionable

2024-05-06T06:26:00.000-07:00

This article was adapted from a Google Testing on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Titus Winters

There are a lot of rules and best practices around unit testing. There are many posts on this blog; there is deeper material in the Software Engineering at Google book; there is specific guidance for every major language; there is guidance on test frameworks, test naming, and dozens of other test-related topics. Isn’t this excessive?

Good unit tests contain several important properties, but you could focus on a key principle: Test failures should be actionable.

When a test fails, you should be able to begin investigation with nothing more than the test’s name and its failure messages—no need to add more information and rerun the test.

Effective use of unit test frameworks and assertion libraries (JUnit, Truth, pytest, GoogleTest, etc.) serves two important purposes. Firstly, the more precisely we express the invariants we are testing, the more informative and less brittle our tests will be. Secondly, when those invariants don’t hold and the tests fail, the failure info should be immediately actionable. This meshes well with Site Reliability Engineering guidance on alerting.

Consider this example of a C++ unit test of a function returning an absl::Status (an Abseil type that returns either an “OK” status or one of a number of different error codes):

EXPECT_TRUE(LoadMetadata().ok());

EXPECT_OK(LoadMetadata());

Sample failure output

load_metadata_test.cc:42: Failure

Value of: LoadMetadata().ok()

Expected: true

Actual: false

load_metadata_test.cc:42: Failure

Value of: LoadMetadata()

Expected: is OK

Actual: NOT_FOUND: /path/to/metadata.bin

If the test on the left fails, you have to investigate why the test failed; the test on the right immediately gives you all the available detail, in this case because of a more precise GoogleTest matcher.

Here are some other posts on this blog that emphasize making test failures actionable:

Writing Descriptive Test Names - If our tests are narrow and sufficiently descriptive, the test name itself may give us enough information to start debugging.
Keep Tests Focused - If we test multiple scenarios in a single test, it’s hard to identify exactly what went wrong.
Prefer Narrow Assertions in Unit Tests - If we have overly wide assertions (such as depending on every field of a complex output protocol buffer), the test may fail for many unimportant reasons. False positives are the opposite of actionable.
Keep Cause and Effect Clear - Refrain from using large global test data structures shared across multiple unit tests, allowing for clear identification of each test’s setup.

isBooleanTooLongAndComplex

2024-04-25T06:14:00.000-07:00

By Yiming Sun

You may have come across some complex, hard-to-read Boolean expressions in your codebase and wished they were easier to understand. For example, let's say we want to decide whether a pizza is fantastic:

// Decide whether this pizza is fantastic.

if ((!pepperoniService.empty() || sausages.size() > 0)

&& (useOnionFlag.get() || hasMushroom(ENOKI, PORTOBELLO)) && hasCheese()) {

...

}

A first step toward improving this is to extract the condition into a well-named variable:

boolean isPizzaFantastic =

(!pepperoniService.empty() || sausages.size() > 0)

&& (useOnionFlag.get() || hasMushroom(ENOKI, PORTOBELLO)) && hasCheese();

if (isPizzaFantastic) {

...

}

However, the Boolean expression is still too complex. It's potentially confusing to calculate the value of isPizzaFantastic from a given set of inputs. You might need to grab a pen and paper, or start a server locally and set breakpoints.

Instead, try to group the details into intermediate Booleans that provide meaningful abstractions. Each Boolean below represents a single well-defined quality, and you no longer need to mix && and || within an expression. Without changing the business logic, you’ve made it easier to see how the Booleans relate to each other:

boolean hasGoodMeat = !pepperoniService.empty() || sausages.size() > 0;

boolean hasGoodVeggies = useOnionFlag.get() || hasMushroom(ENOKI, PORTOBELLO);

boolean isPizzaFantastic = hasGoodMeat && hasGoodVeggies && hasCheese();

Another option is to hide the logic in a separate method. This also offers the possibility of early returns using guard clauses, further reducing the need to keep track of intermediate states:

boolean isPizzaFantastic() {

if (!hasCheese()) {

return false;

}

if (pepperoniService.empty() && sausages.size() == 0) {

return false;

}

return useOnionFlag.get() || hasMushroom(ENOKI, PORTOBELLO);
}

How I Learned To Stop Writing Brittle Tests and Love Expressive APIs

2024-04-18T05:50:00.000-07:00

This article was adapted from a Google Testing on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Titus Winters

A valuable but challenging property for tests is “resilience,” meaning a test should only fail when something important has gone wrong. However, an opposite property may be easier to see: A “brittle” test is one that fails not for real problems that would break in production, but because the test itself is fragile for innocuous reasons. Error messages, changing the order of metadata headers in a web request, or the order of calls to a heavily-mocked dependency can often cause a brittle test to fail.

Expressive test APIs are a powerful tool in the fight against brittle, implementation-detail heavy tests. A test written with IsSquare(output) is more expressive (and less brittle) than a test written with details such as JsonEquals(.width = 42, .length = 42), in cases where the size of the square is irrelevant. Similar expressive designs might include unordered element matching for hash containers, metadata comparisons for photos, and activity logs in processing objects, just to name a few.

As an example, consider this C++ test code:

absl::flat_hash_set<int> GetValuesFromConfig(const Config&);

TEST(ConfigValues, DefaultConfigsArePrime) {

// Note the strange order of these values. BAD CODE, DON’T DO THIS!

EXPECT_THAT(GetValuesFromConfig(Config()), ElementsAre(29, 17, 31));

}

The reliance on hash ordering makes this test brittle, preventing improvements to the API being tested. A critical part of the fix to the above code was to provide better test APIs that allowed engineers to more effectively express the properties that mattered. Thus we added UnorderedElementsAre to the GoogleTest test framework and refactored brittle tests to use that:

TEST(ConfigValues, DefaultConfigsArePrimeAndOrderDoesNotMatter) {

EXPECT_THAT(GetValuesFromConfig(Config()), UnorderedElementsAre(17, 29, 31));

}

It’s easy to see brittle tests and think, “Whoever wrote this did the wrong thing! Why are these tests so bad?” But it’s far better to see that these brittle failures are a signal indicating where the available testing APIs are missing, under-advertised, or need attention.

Brittleness may indicate that the original test author didn’t have access to (or didn’t know about) test APIs that could more effectively identify the salient properties that the test meant to enforce. Without the right tools, it’s too easy to write tests that depend on irrelevant details, making those tests brittle.

If your tests are brittle, look for ways to narrow down golden diff tests that compare exact pixel layouts or log outputs. Discover and learn more expressive APIs. File feature requests with the owners of the upstream systems.

If you maintain infrastructure libraries and can’t make changes because of brittleness, think about what your users are lacking, and invest in expressive test APIs.

Prefer Narrow Assertions in Unit Tests

2024-04-04T05:47:00.000-07:00

This article was adapted from a Google Testing on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

by Kai Kent

Your project is adding a loyalty promotion feature, so you add a new column CREATION_DATE to the ACCOUNT table. Suddenly the test below starts failing. Can you spot the problem?

TEST_F(AccountTest, UpdatesBalanceAfterWithdrawal) {

ASSERT_OK_AND_ASSIGN(Account account,

database.CreateNewAccount(/*initial_balance=*/5000));

ASSERT_OK(account.Withdraw(3000));

const Account kExpected = { .balance = 2000, /* a handful of other fields */ };

EXPECT_EQ(account, kExpected);

}

You forgot to update the test for the newly added column; but the test also has an underlying problem:

It checks for full equality of a potentially complex object, and thus implicitly tests unrelated behaviors. Changing anything in Account, such as adding or removing a field, will cause all the tests with a similar pattern to fail. Broad assertions are an easy way to accidentally create brittle tests - tests that fail when anything about the system changes, and need frequent fixing even though they aren't finding real bugs.

Instead, the test should use narrow assertions that only check the relevant behavior. The example test should be updated to only check the relevant field account.balance:

TEST_F(AccountTest, UpdatesBalanceAfterWithdrawal) {

ASSERT_OK_AND_ASSIGN(Account account,

database.CreateNewAccount(/*initial_balance=*/5000));

ASSERT_OK(account.Withdraw(3000));

EXPECT_EQ(account.balance, 2000);

}

Broad assertions should only be used for unit tests that care about all of the implicitly tested behaviors, which should be a small minority of unit tests. Prefer to have at most one such test that checks for full equality of a complex object for the common case, and use narrow assertions for all other cases.

Similarly, when writing frontend unit tests, use one screenshot diff test to verify the layout of your UI, but test individual behaviors with narrow DOM assertions.

For testing large protocol buffers, some languages provide libraries for verifying a subset of proto fields in a single assertion, such as:

.comparingExpectedFieldsOnly() in Java (Truth Protobuf Extension)
protocmp.FilterField in Go (protocmp)

What’s in a Name?

2024-03-26T05:34:00.000-07:00

by Adam Raider

“There are only two hard things in computer science: cache invalidation and naming things.” —Phil Karlton

Have you ever read an identifier only to realize later it doesn’t do what you expected? Or had to read the implementation in order to understand an interface? These indirections eat up our cognitive bandwidth and make our work more difficult. We spend far more time reading code than we do writing it; thoughtful names can save the reader (and writer) a lot of time and frustration. Here are some naming tips:

Spend time considering names—it’s worth it. Don’t default to the first name that comes to mind. The more public the name, the more expensive it is to change. Past a certain scale, names become infeasible to change, especially for APIs. Pay attention to a name in proportion to the cost of renaming it later. If you’re feeling stuck, consider running a new name by a teammate.
Describe behavior. Encourage naming based on what functions do rather than when the functions are called. Avoid prefixes like “handle” or “on” as they describe when and provide no added meaning:

button.listen('click', handleClick)

button.listen('click', addItemToCart)

Reveal intent with a contextually appropriate level of abstraction:

High-abstraction functions describe the what and operate on high-level types.
Lower-abstraction functions describe the how and operate on lower-level types.

For example, logout might call into clearUserToken, and recordWithCamera might call into parseStreamBytes.

Prefer unique, precise names. Are you frequently asking for the UserManager? Manager, Util, and similar suffixes are a common but imprecise naming convention. What does it do? It manages! If you’re struggling to come up with a more precise name, consider splitting the class into smaller ones.
Balance clarity and conciseness—use abbreviations with care. Commonly used abbreviations, such as HTML, i18n, and RPC, can aid communication but less-known ones can confuse your average readers. Ask yourself, “Will my readers immediately understand this label? Will a reader five years from now understand it?”
Avoid repetition and filler words. Or in other words, don’t say the same thing twice. It adds unnecessary visual noise:

userData.userBirthdayDate

user.birthDate

Software changes—names should, too. If you see an identifier that doesn’t aptly describe itself—fix it!

Learn more about identifier naming in this post: IdentifierNamingPostForWorldWideWebBlog.

Increase Test Fidelity By Avoiding Mocks

2024-02-27T10:43:00.000-08:00

This article was adapted from a Google Testing on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Andrew Trenk and Dillon Bly

Replacing your code’s dependencies with mocks can make unit tests easier to write and faster to run. However, among other problems, using mocks can lead to tests that are less effective at catching bugs.

The fidelity of a test refers to how closely the behavior of the test resembles the behavior of the production code. A test with higher fidelity gives you higher confidence that your code will work properly.

When specifying a dependency to use in a test, prefer the highest-fidelity option. Learn more in the Test Doubles chapter of the Software Engineering at Google book.

Try to use the real implementation. This provides the most fidelity, because the code in the implementation will be executed in the test. There may be tradeoffs when using a real implementation: they can be slow, non-deterministic, or difficult to instantiate (e.g., it connects to an external server). Use your judgment to decide if a real implementation is the right choice.
Use a fake if you can’t use the real implementation. A fake is a lightweight implementation of an API that behaves similarly to the real implementation, e.g., an in-memory database. A fake ensures a test has high fidelity, but takes effort to write and maintain; e.g., it needs its own tests to ensure that it conforms to the behavior of the real implementation. Typically, the owner of the real implementation creates and maintains the fake.
Use a mock if you can’t use the real implementation or a fake. A mock reduces fidelity, since it doesn’t execute any of the actual implementation of a dependency; its behavior is specified inline in a test (a technique known as stubbing), so it may diverge from the behavior of the real implementation. Mocks provide a basic level of confidence that your code works properly, and can be especially useful when testing a code path that is hard to trigger (e.g., an error condition such as a timeout).
(Note: Although “mocks” are objects created using mocking frameworks such as Mockito or unittest.mock, the same problems will occur if you manually create your own implementation within tests.)

A low-fidelity test: Dependencies are replaced with mocks. Try to avoid this.

A high-fidelity test: Dependencies use real implementations or fakes. Prefer this.

@Mock OrderValidator validator;

@Mock PaymentProcessor processor;

...

ShoppingCart cart =

new ShoppingCart(

validator, processor);

OrderValidator validator =

createValidator();

PaymentProcessor processor =

new FakeProcessor();

...

ShoppingCart cart =

new ShoppingCart(

validator, processor);

Aim for as much fidelity as you can achieve without increasing the size of a test. At Google, tests are classified by size. Most tests should be small: they must run in a single process and must not wait on a system or event outside of their process. Increasing the fidelity of a small test is often a good choice if the test stays within these constraints. A healthy test suite also includes medium and large tests, which have higher fidelity since they can use heavyweight dependencies that aren’t feasible to use in small tests, e.g., dependencies that increase execution times or call other processes.

Let Code Speak for Itself

2023-12-12T08:06:00.000-08:00

by Shiva Garg and Francois Aube

Comments can be invaluable for understanding and maintaining a code base. But excessive comments in code can become unhelpful clutter full of extraneous and/or outdated detail.

Comments that offer useless (or worse, obsolete) information hurt readability. Here are some tips to let your code speak for itself:

Write comments to explain the “why” behind a certain approach in code. The comment below has two good reasons to exist: documenting non-obvious behavior and answering a question that a reader is likely to have (i.e. why doesn’t this code render directly on the screen?):

// Eliminate flickering by rendering the next frame off-screen and swapping into the

// visible buffer.

RenderOffScreen();

SwapBuffers();

Use well-named identifiers to guide the reader and reduce the need for comments:

// Payout should not happen if the user is

// in an ineligible country.

std::unordered_set<std::string> ineligible =

{"Atlantis", "Utopia"};

if (!ineligible.contains(country)) {

Payout(user.user_id);

}

if (IsCountryEligibleForPayout(country)) { Payout(user.user_id); }

Write function comments (a.k.a. API documentation) that describe intended meaning and purpose, not implementation details. Choose unambiguous function signatures that callers can use without reading any documentation. Don’t explain inner details that could change without affecting the contract with the caller:

// Reads an input string containing either a

// number of milliseconds since epoch or an

// ISO 8601 date and time. Invokes the

// Sole, Laces, and ToeCap APIs, then

// returns an object representing the Shoe

// available then or nullptr if none were.

Shoe* ModelAvailableAt(char* time);

// Returns the Shoe that was available for

// purchase at `time`. If no model was

// available, throws a runtime_error.

Shoe ModelAvailableAt(time_t time);

Omit comments that state the obvious. Superfluous comments increase code maintenance when code gets refactored and don’t add value, only overhead to keep these comments current:

// Increment counter by 1.

counter++;

Learn more about writing good comments: To Comment or Not to Comment?, Best practices for writing code comments

Exceptional Exception Handling

2023-12-05T05:19:00.000-08:00

by Yiming Sun

Have you ever seen huge exception-handling blocks? Here is an example in Java, although you may have seen similar problems in Python, TypeScript, Kotlin, or any language that supports exceptions.

Let's assume we are calling bakePizza() to bake a pizza, and it can be overbaked, throwing a PizzaOverbakedException.

class PizzaOverbakedException extends Exception {};

void bakePizza () throws PizzaOverbakedException {};

try {

// 100+ lines of code to prepare pizza ingredients.

...

bakePizza();

// Another 100+ lines of code to deliver pizza to a customer.

...

} catch (Exception e) {

throw new IllegalStateException(); // Root cause ignored while throwing new exception.

}

Here are the problems with the above code:

Obscuring the logic. The method bakePizza(), is obscured by the additional lines of code of preparation and delivery, so unintended exceptions from preparation and delivery may be caught.
Catching the general exception. catch (Exception e) will catch everything, despite that we might only want to handle PizzaOverbakedException here.
Rethrowing a general exception, with the original exception ignored. This means that the root cause is lost - we don't know what exactly goes wrong with pizza baking while debugging.

Here is a better alternative, rewritten to avoid the problems above.

class PizzaOverbakedException extends Exception {};

void bakePizza () throws PizzaOverbakedException {};

// 100+ lines of code to prepare pizza ingredients.

...

try {

bakePizza();

} catch (PizzaOverbakedException e) { // Other exceptions won’t be caught.

// Rethrow a more meaningful exception; so that we know pizza is overbaked.

throw new IllegalStateException(“You burned the pizza!”, e);

}

// Another 100+ lines of code to deliver pizza to a customer.

...

Clean Up Code Cruft

2023-11-28T05:00:00.000-08:00

By Per Jacobsson

The book Clean Code discusses a camping rule that is good to keep in the back of your mind when writing code:

Leave the campground cleaner than you found it

So how does that fit into software development? The thinking is this: When you make changes to code that can potentially be improved, try to make it just a little bit better.

This doesn't necessarily mean you have to go out of your way to do huge refactorings. Changing something small can go a long way:

Rename a variable to something more descriptive.
Break apart a huge function into a few logical pieces.
Fix a lint warning.
Bring an outdated comment up to date.
Extract duplicated lines to a function.
Write a unit test for an untested function.
Whatever other itch you feel like scratching.

Cleaning up the small things often makes it easier to see and fix the bigger issues.

But what about "If it's not broken, don't fix it"? Changing code can be risky, right? There's no obvious rule, but if you're always afraid to change your code, you have bigger problems. Cruft in code that is actively being changed is like credit card debt. Either you pay it off, or you eventually go bankrupt.

Unit tests help mitigate the risk of changing code. When you're doing cleanup work, be sure there are unit tests for the things you're about to change. This may mean writing a few new ones yourself.

If you’re working on a change and end up doing some minor cleanup, you can often include these cleanups in the same change. Be careful to not distract your code reviewer by adding too many unrelated cleanups. An option that works well is to send the cleanup fixes in multiple tiny changes that are small enough to just take a few seconds to review.

As mentioned in the book: "Can you imagine working on a project where the code simply got better as time passed?"

“Clean Code: A Handbook of Agile Software Craftsmanship” by Robert C. Martin was published in 2008.

Write Clean Code to Reduce Cognitive Load

2023-11-06T05:45:00.000-08:00

By Andrew Trenk

Do you ever read code and find it hard to understand? You may be experiencing cognitive load!

Cognitive load refers to the amount of mental effort required to complete a task. When reading code, you have to keep in mind information such as values of variables, conditional logic, loop indices, data structure state, and interface contracts. Cognitive load increases as code becomes more complex. People can typically hold up to 5–7 separate pieces of information in their short-term memory (source); code that involves more information than that can be difficult to understand.

Cognitive load is often higher for other people reading code you wrote than it is for yourself, since readers need to understand your intentions. Think of the times you read someone else’s code and struggled to understand its behavior. One of the reasons for code reviews is to allow reviewers to check if the changes to the code cause too much cognitive load. Be kind to your co-workers: reduce their cognitive load by writing clean code.

The key to reducing cognitive load is to make code simpler so it can be understood more easily by readers. This is the principle behind many code health practices. Here are some examples:

Limit the amount of code in a function or file. Aim to keep the code concise enough that you can keep the whole thing in your head at once. Prefer to keep functions small, and try to limit each class to a single responsibility.
Create abstractions to hide implementation details. Abstractions such as functions and interfaces allow you to deal with simpler concepts and hide complex details. However, remember that over-engineering your code with too many abstractions also causes cognitive load.
Simplify control flow. Functions with too many if statements or loops can be hard to understand since it is difficult to keep the entire control flow in your head. Hide complex logic in helper functions, and reduce nesting by using early returns to handle special cases.
Minimize mutable state. Stateless code is simpler to understand. For example, avoid mutable class fields when possible, and make types immutable.
Include only relevant details in tests. A test can be hard to follow if it includes boilerplate test data that is irrelevant to the test case, or relevant test data is hidden in helper functions.
Don’t overuse mocks in tests. Improper use of mocks can lead to tests that are cluttered with calls that expose implementation details of the system under test.

Learn more about cognitive load in the book The Programmer’s Brain, by Felienne Hermans.

Include Only Relevant Details In Tests

2023-10-30T05:43:00.001-07:00

This article was adapted from a Google Testing on the Toilet (TotT) episode. You can download a printer-friendly version of this TotT episode and post it in your office.

By Dagang Wei

What problem in the code below makes the test hard to follow?

def test_get_balance(self):

settings = BankSettings(FDIC_INSURED, REGULATED, US_BASED)

account = Account(settings, ID, BALANCE, ADDRESS, NAME, EMAIL, PHONE)

self.assertEqual(account.GetBalance(), BALANCE)

The problem is that there is a lot of noise in the account creation code, which makes it hard to tell which details are relevant to the assert statement.

But going from one extreme to the other can also make the test hard to follow:

def test_get_balance(self):

account = _create_account()

self.assertEqual(account.GetBalance(), BALANCE)

Now the problem is that critical details are hidden in the _create_account() helper function, so it’s not obvious where the BALANCE field comes from. In order to understand the test, you need to switch context by diving into the helper function.

A good test should include only details relevant to the test, while hiding noise:

def test_get_balance():

account = _create_account(BALANCE)

self.assertEqual(account.GetBalance(), BALANCE)

By following this advice, it should be easy to see the flow of data throughout a test. For example:

Bad (flow of data is hidden):

Good (flow of data is clear):

def test_bank_account_overdraw_fails(self):

account = _create_account()

outcome = _overdraw(account)

self._assert_withdraw_failed(

outcome, account)

def _create_account():

settings = BankSettings(...)

return Account(settings, BALANCE, ...)

def _overdraw(account):

# Boilerplate code

...

return account.Withdraw(BALANCE + 1)

def _assert_withdraw_failed(

self, outcome, account):

self.assertEqual(outcome, FAILED)

self.assertEqual(

account.GetBalance(), BALANCE)

def test_bank_account_overdraw_fails(self):

account = _create_account(BALANCE)

outcome = _withdraw(account, BALANCE + 1)

self.assertEqual(outcome, FAILED)

self.assertEqual(

account.GetBalance(), BALANCE)

def _create_account(balance):

settings = BankSettings(...)

return Account(settings, balance, ...)

def _withdraw(account, amount):

# Boilerplate code

...

return account.Withdraw(amount)

Simplify Your Control Flows

2023-10-24T05:46:00.000-07:00

By Jeff Hoy

When adding loops and conditionals, even simple code can become difficult to understand.
Consider this change:

if (commode.HasPreferredCustomer()) {	if (commode.HasPreferredCustomer()) {
commode.WarmSeat();	commode.WarmSeat();
	} else if (commode.CustomerOnPhone()) {
	commode.ChillSeat();
}	}

While the above change may seem simple, even adding a single else statement can make the code harder to follow since the complexity of code grows quickly with its size. Below we see the code surrounding the above snippet; the control flow on the right illustrates how much a reader needs to retain:

while (commode.StillOccupied()) {

if (commode.HasPreferredCustomer()) {

commode.WarmSeat();

} else if (commode.CustomerOnPhone()) {

commode.ChillSeat();

}

if (commode.ContainsKale()) {

commode.PrintHealthCertificate();

break;

}

Code Control Flow with 5 structures and 9 edges:

challenging for a reader to retain in memory.

In order to fully understand the code, the reader needs to keep the entire control flow in their head. However, the retention capacity of working memory is limited (source) Code path complexity will also challenge the reader, and can be measured using cyclomatic complexity.

To reduce cognitive overhead of complex code, push implementation logic down into functions and methods. For example, if the if/else structure in the above code is moved into an AdjustSeatTemp() method, the reviewer can review the two blocks independently, each having a much simpler control graph:

while (commode.StillOccupied()) {

commode.AdjustSeatTemp();

if (commode.ContainsKale()) {

commode.PrintHealthCertificate();

break;

}

3 control structures and 5 edges: easier to remember

Commode::AdjustSeatTemp()

with 2 structures and 4 edges

Avoiding complexity makes code easier to follow. In addition, code reviewers are more likely to identify logic errors, and maintainers are less likely to introduce complex code.

Improve Readability With Positive Booleans

2023-10-17T05:50:00.003-07:00

By Max Kanat-Alexander

Reading healthy code should be as easy as reading a book in your native language. You shouldn’t have to stop and puzzle over what a line of code is doing. One small trick that can assist with this is to make boolean checks about something positive rather than about something negative.

Here’s an extreme example:

if not nodisable_kryponite_shield:

devise_clever_escape_plan()

else:

engage_in_epic_battle()

What does that code do? Sure, you can figure it out, but healthy code is not a puzzle, it’s a simple communication. Let’s look at two principles we can use to simplify this code.

1. Name your flags and variables in such a way that they represent the positive check you wish to make (the presence of something, something being enabled, something being true) rather than the negative check you wish to make (the absence of something, something being disabled, something being false).

if not enable_kryponite_shield:

devise_clever_escape_plan()

else:

engage_in_epic_battle()

That is already easier to read and understand than the first example.

2. If your conditional looks like “if not … else …” then reverse it to put the positive case first.

if enable_kryponite_shield:

engage_in_epic_battle()

else:

devise_clever_escape_plan()

Now the intention of the code is immediately obvious.

There are many other contexts in which this gives improvements to readability. For example, the command foo --disable_feature=False is harder to read and think about than
foo --enable_feature=True, particularly when you change the default to enable the feature.

There are some exceptions (for example, in Python, if foo is not None could be considered a “positive check” even though it has a “not” in it), but in general checking the presence or absence of a positive is simpler for readers to understand than checking the presence or absence of a negative.

Shell Scripts: Stay Small & Simple

2023-10-11T05:21:00.002-07:00

A version of this post originally appeared in Google bathrooms worldwide as a Google Testing on the Toilet episode. You can download a printer-friendly version to display in your office.

By David Mandelberg

Shell scripts (including Bash scripts) can be convenient for automating simple command line procedures, and they are often better than keeping complicated commands in a single developer's history. However, shell scripts can be hard to understand and maintain, and are typically not as well-supported as other programming languages. Shell scripts have less support for unit testing, and there is likely a lower chance that somebody reading one will be experienced with the language.

Python, Go, or other general-purpose languages are often better choices than shell. Shell is convenient for some simple use cases, and the Google shell style guide can help with writing better shell scripts. But it is difficult, even for experienced shell scripters, to mitigate the risks of its many surprising behaviors. So whenever possible, use shell scripts only for small, simple use cases, or avoid shell entirely.

Here are some examples of mistakes that are far too easy to make when writing a shell script (see Bash Pitfalls for many more):

Forgetting to quote something can have surprising results, due to shell's complicated evaluation rules. E.g., even if a wildcard is properly quoted, it can still be unexpectedly expanded elsewhere:

$ msg='Is using bash a pro? Or a con?'

$ echo $msg # Note that there's a subdirectory called 'proc' in the current directory.

Is using bash a proc Or a con? # ? was unexpectedly treated as a wildcard.

Many things that would be function arguments in other languages are command line arguments in shell. Command line arguments are world-readable, so they can leak secrets:

$ curl -H "Authorization: Bearer ${SECRET}" "$URL" &

$ ps aux # The current list of processes shows the secret.

By default, the shell ignores all errors from commands, which can cause severe bugs if code assumes that earlier commands succeeded. The command set -e can appear to force termination at the first error, but its behavior is inconsistent. For example, set -e does not affect some commands in pipelines (like false in false | cat), nor will it affect some command substitutions (such as the false in export FOO="$(false)"). Even worse, its behavior inside a function depends on how that function is called.

Many things run in subshells, which can (often unexpectedly) hide changes to variables from the main shell. It can also make manual error handling harder, compounding the issue above:

$ run_or_exit() { "$@" || exit $?; } # Executes the arguments then exits on failure.

$ foo="$(run_or_exit false)" # Exits the $() subshell, but the script continues.