Google Testing Blog

Code Health: To Comment or Not to Comment?

Monday, July 17, 2017

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 Dori Reuveni and Kevin Bourrillion
While reading code, often there is nothing more helpful than a well-placed comment. However, comments are not always good. Sometimes the need for a comment can be a sign that the code should be refactored.
Use a comment when it is infeasible to make your code self-explanatory. If you think you need a comment to explain what a piece of code does, first try one of the following:

Introduce an explaining variable.

// Subtract discount from price.
finalPrice = (numItems * itemPrice)
    - min(5, numItems) * itemPrice * 0.1;

price = numItems * itemPrice;
discount =
    min(5, numItems) * itemPrice * 0.1;
finalPrice = price - discount;

Extract a method.

// Filter offensive words.
for (String word : words) { ... }

filterOffensiveWords(words);

Use a more descriptive identifier name.

int width = ...; // Width in pixels.

int widthInPixels = ...;

Add a check in case your code has assumptions.

// Safe since height is always > 0.
return width / height;

checkArgument(height > 0);
return width / height;

There are cases where a comment can be helpful:

Reveal your intent: explain why the code does something (as opposed to what it does).

// Compute once because it’s expensive.
Protect a well-meaning future editor from mistakenly “fixing” your code.

// Create a new Foo instance because Foo is not thread-safe.
Clarification: a question that came up during code review or that readers of the code might have.

// Note that order matters because...
Explain your rationale for what looks like a bad software engineering practice.

@SuppressWarnings("unchecked") // The cast is safe because...

On the other hand, avoid comments that just repeat what the code does. These are just noise:

// Get all users.
userService.getAllUsers();

// Check if the name is empty.
if (name.isEmpty()) { ... }

Evolution of GTAC and Engineering Productivity

Wednesday, July 12, 2017

When Google first hosted GTAC in 2006, we didn’t know what to expect. We kicked off this conference with the intention to share our innovation in test automation, learn from others in the industry and connect with academia. Over the last decade we’ve had great participation and had the privilege to host GTAC in North America, Europe and Asia -- largely thanks to the many of you who spoke, participated and connected!
In the recent months, we’ve been taking a hard look at the discipline of Engineering Productivity as a logical next step in the evolution of test automation. In that same vein, we’re going to rethink what an Engineering Productivity focused conference should look like today. As we pivot, we will be extending these changes to GTAC and because we expect changes in theme, content and format, we are canceling the upcoming event scheduled in London this November. We’ll be bringing the event back in 2018 with a fresh outlook and strategy.
While we know this may be disappointing for many of the folks who were looking forward to GTAC, we’re excited to come back with a new format which will serve this conference well in today’s environment.

Code Health: Too Many Comments on Your Code Reviews?

Monday, June 19, 2017

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 Tom O'Neill
Code reviews can slow down an individual code change, but they’re also an opportunity to improve your code and learn from another intelligent, experienced engineer. How can you get the most out of them? Aim to get most of your changes approved in the first round of review, with only minor comments. If your code reviews frequently require multiple rounds of comments, these tips can save you time.
Spend your reviewers’ time wisely—it’s a limited resource. If they’re catching issues that you could easily have caught yourself, you’re lowering the overall productivity of your team. Before you send out the code review:

Re-evaluate your code: Don’t just send the review out as soon as the tests pass. Step back and try to rethink the whole thing—can the design be cleaned up? Especially if it’s late in the day, see if a better approach occurs to you the next morning. Although this step might slow down an individual code change, it will result long-term in greater average throughput.

Consider an informal design discussion: If there’s something you’re not sure about, pair program, talk face-to-face, or send an early diff and ask for a “pre-review” of the overall design.

Self-review the change: Try to look at the code as critically as possible from the standpoint of someone who doesn’t know anything about it. Your code review tool can give you a radically different view of your code than the IDE. This can easily save you a round trip.

Make the diff easy to understand: Multiple changes at once make the code harder to review. When you self-review, look for simple changes that reduce the size of the diff. For example, save significant refactoring or formatting changes for another code review.

Don’t hide important info in the submit message: Put it in the code as well. Someone reading the code later is unlikely to look at the submit message.

When you’re addressing code review comments:

Re-evaluate your code after addressing non-trivial comments: Take a step back and really look at the code with fresh eyes. Once you’ve made one set of changes, you can often find additional improvements that are enabled or suggested by those changes. Just as with any refactoring, it may take several steps to reach the best design.

Understand why the reviewer made each comment: If you don’t understand the reasoning behind a comment, don’t just make the change—seek out the reviewer and learn something new.

Answer the reviewer’s questions in the code: Don’t just reply—make the code easier to understand (e.g., improve a variable name, change a boolean to an enum) or add a comment. Someone else is going to have the same question later on.

Code Health: Reduce Nesting, Reduce Complexity

Monday, June 05, 2017

Code with too much nesting

Code with less nesting

response = server.Call(request)
 
if response.GetStatus() == RPC.OK:
  if response.GetAuthorizedUser():
    if response.GetEnc() == 'utf-8':
      if response.GetRows():
        vals = [ParseRow(r) for r in 
                response.GetRows()]
        avg = sum(vals) / len(vals)
        return avg, vals
      else:
        raise EmptyError()
    else:
      raise AuthError('unauthorized')
  else:
    raise ValueError('wrong encoding')
else:
  raise RpcError(response.GetStatus())

response = server.Call(request)
 
if response.GetStatus() != RPC.OK:
  raise RpcError(response.GetStatus())

if not response.GetAuthorizedUser():
  raise ValueError('wrong encoding')

if response.GetEnc() != 'utf-8':
  raise AuthError('unauthorized')
 
if not response.GetRows():
  raise EmptyError()

vals = [ParseRow(r) for r in 
        response.GetRows()]
avg = sum(vals) / len(vals)
return avg, vals

wrong encoding"unauthorized"This bug is easier to see in the refactored version, since the checks occur right as the errors are handled.guard clausesthe refactored version is much easier to read and maintain
Here are some rules of thumb for reducing nesting in your code:

Keep conditional blocks short. It increases readability by keeping things local.

Consider refactoring when your loops and branches are more than 2 levels deep.

Think about moving nested logic into separate functions. For example, if you need to loop through a list of objects that each contain a list (such as a protocol buffer with repeated fields), you can define a function to process each object instead of using a double nested loop.

GTAC Diversity Scholarship

Monday, May 22, 2017

by Lesley Katzen on behalf of the GTAC Diversity Committee

Be 18 years of age or older.

Be from a traditionally underrepresented group in technology.

Work or study in Computer Science, Computer Engineering, Information Technology, or a technical field related to software testing.

Be able to attend core dates of GTAC, November 14th - 15th 2017 in London, England.

To apply:formregister
What the scholarship covers:https://www.google.com/events/policy/anti-harassmentpolicy.html

Testing Blog

Code Health: To Comment or Not to Comment?

Evolution of GTAC and Engineering Productivity

Code Health: Too Many Comments on Your Code Reviews?

Code Health: Reduce Nesting, Reduce Complexity

GTAC Diversity Scholarship

Labels

Archive

Feed

Subscribe by Email

Company-wide

Products

Developers