Google Testing Blog: September 2023

Communicate Design Tradeoffs Visually

Thursday, September 21, 2023

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 Tim Lyakhovetskiy

A goal of any written design or project proposal is to present and evaluate alternatives. However, documents that include multiple solutions can be difficult to read when the qualities of each solution are not clearly expressed.

A common approach to simplifying proposals is to use “pros and cons” for each alternative, but this leads to biased writing since the pros and cons may be weighed differently depending on the reader’s priorities.

In this example, can you quickly tell how this option would measure up against others?

Option 1 - Optimize Shoelace Untangling Wizard in ShoeApp UI

Pros

Shoelace Untangling Wizard UI will use 10% less CPU
Less than one quarter to implement
Users will see 100ms less UI lag

Cons

Security risk (shoelace colors exposed) until ShoeAppBackend team fixes lacing API
ShoeAppBackend will be blocked for 3 months
User documentation for Shoelace Untangling Wizard UI has to change

This format requires the reader to remember many details in order to evaluate which option they prefer. Instead, express tradeoffs using impact on qualities. There are many common quality attributes including Performance, Security, Maintainability, Usability, Testability, Scalability, and Cost.

Use colors and symbols in a table (➖ negative, ～ somewhat negative, ➕ positive) to make it easy for readers to parse your ideas. The symbols are needed for accessibility, e.g. color-blindness and screen readers.

Option 1 - Optimize Shoelace Untangling Wizard in ShoeApp UI

Usability	➕ Users will see 100ms less UI lag
Usability	～ User documentation for Shoelace Untangling Wizard UI has to change
Security	➖ Security risk (shoelace colors exposed) until ShoeAppBackend fixes lacing API
Partner impact	➖ ShoeAppBackend will be blocked for 3 months
Performance	➕ Shoelace Untangling Wizard UI will use 10% less CPU
Schedule/Cost	➕ Less than one quarter to implement

Notice that the content uses approximately the same space but communicates more visually. The benefit is even greater when there are many alternatives/attributes, as it’s possible to evaluate the whole option at a glance.

No comments

Else Nuances

Wednesday, September 13, 2023

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 Sam Lee and Stan Chan If your function exits early in an if statement, using or not using an else clause is equivalent in terms of behavior. However, the proper use of else clauses and guard clauses (lack of else) can help emphasize the intent of the code to the reader.Consider the following guidelines to help you structure your functions:

Use a guard clause to handle special cases upfront, so that the rest of the code can focus
on the core logic. A guard clause checks a criterion and fails fast or returns early if it is not
met, which reduces nesting (see the Reduce Nesting article).

def parse_path(path: str) -> Path:

if not path:

raise ValueError(“path is empty.”)

else:

# Nested logic here.

...

def parse_path(path: str) -> Path:

if not path:

raise ValueError(“path is empty.”)

# No nesting needed for the valid case.

...

Use else if it is part of the core responsibility. Prefer to keep related conditional logic
syntactically grouped together in the same if...else structure if each branch is relevant to the
core responsibility of the function. Grouping logic in this way emphasizes the complementary
nature of each condition. The complementary nature is emphasized explicitly by the else
statement, instead of being inferred and relying on the resulting behavior of the prior return
statement.

def get_favicon(self) -> Icon:

if self.user.id is None:

return Icon.SIGNED_OUT

if self.browser.incognito: return Icon.INCOGNITO

if not self.new_inbox_items:

return Icon.EMPTY;

return Icon.HAS_ITEMS

def get_favicon(self) -> Icon:

if self.user.id is None:

return Icon.SIGNED_OUT

elif self.browser.incognito:

return Icon.INCOGNITO

elif not self.new_inbox_items:

return Icon.EMPTY

else:

return Icon.HAS_ITEMS

# No trailing return is needed or allowed.

When it’s idiomatic, use a switch (or similar) statement instead of if...else statements. (switch/when in Go/Kotlin can accept boolean conditions like if...else.)Not all scenarios will be clear-cut for which pattern to use; use your best judgment to choose between these two styles. A good rule of thumb is use a guard if it's a special case, use else if its core logic. Following these guidelines can improve code understandability by emphasizing the connections between different logical branches.

No comments

Use Abstraction to Improve Function Readability

Wednesday, September 06, 2023

By Palak Bansal and Mark Manley

Which version of the createPizza function below is easier to understand?

func createPizza(order *Order) *Pizza {

pizza := &Pizza{Base: order.Size,

Sauce: order.Sauce,

Cheese: “Mozzarella”}

if order.kind == “Veg” {

pizza.Toppings = vegToppings

} else if order.kind == “Meat” {

pizza.Toppings = meatToppings

}

oven := oven.New()

if oven.Temp != cookingTemp {

for (oven.Temp < cookingTemp) {

time.Sleep(checkOvenInterval)

oven.Temp = getOvenTemp(oven)

}

if !pizza.Baked {

oven.Insert(pizza)

time.Sleep(cookTime)

oven.Remove(pizza)

pizza.Baked = true

}

box := box.New()

pizza.Boxed = box.PutIn(pizza)

pizza.Sliced = box.SlicePizza(order.Size)

pizza.Ready = box.Close()

return pizza

}

func createPizza(order *Order) *Pizza {

pizza := prepare(order)

bake(pizza)

box(pizza)

return pizza

}

func prepare(order *Order) *Pizza {

pizza := &Pizza{Base: order.Size,

Sauce: order.Sauce,

Cheese: “Mozzarella”}

addToppings(pizza, order.kind)

return pizza

}

func addToppings(pizza *Pizza, kind string) {

if kind == “Veg” {

pizza.Toppings = vegToppings

} else if kind == “Meat” {

pizza.Toppings = meatToppings

}

func bake(pizza *Pizza) {

oven := oven.New()

heatOven(oven)

bakePizza(pizza, oven)

}

func heatOven(oven *Oven) { … }

func bakePizza(pizza *Pizza, oven *Oven) { … }

func box(pizza *Pizza) { … }

You probably said the right-hand side is easier, but why? The left side mixes together several levels of abstraction: low-level implementation details (e.g., how to heat the oven), intermediate-level functions (e.g., how to bake pizza), and high-level abstractions (e.g., preparing, baking, and boxing the pizza).

The right side is easier to follow because the functions have a consistent level of abstraction, providing a top-down narrative of the code’s logic. createPizza is a high-level function that delegates the preparing, baking, and boxing steps to lower-level specialized functions with intuitive names. Those functions, in turn, delegate to their own lower-level specialized functions (e.g., heatOven) until they reach a function that handles implementation details without needing to call other functions.

Avoid mixing different abstraction layers into a single function. Nest functions at equal abstraction levels to provide a narrative. This self-documenting style is simpler to follow, debug, and reuse.

You can learn more about this topic in the book Clean Code by Robert C. Martin.

No comments

Testing Blog

Communicate Design Tradeoffs Visually

Else Nuances

Use Abstraction to Improve Function Readability

Labels

Archive

Feed