Google Code Health Guide: Naming, Commit Messages, and Linking to Issue Reports

Thanks to an attentive fan for pointing out errors; the figure legends have been corrected and the first line of commit messages should now appear on its own line.

Previous link: [Series] Google Code Health Guide (Part 1)

Key points:

Be careful with overly long names.

Write good commit messages.

Link code changes to defect reports.

Creating long identifiers is easy, but excessively long names can reduce readability. While longer names can be more descriptive, they should remain clear and precise. Guidelines include omitting type‑obvious descriptors, irrelevant details, information inferable from context, and generic identifiers such as data, state, manager, etc.

Guideline 1: Omit variable type descriptions when they are obvious.

Guideline 2: Omit irrelevant details.

Guideline 3: Omit information that can be derived from context.

Guideline 4: Avoid generic identifiers that could be used everywhere.

Examples of poor names include data, state, amount, number, value, manager, engine, object, entity, instance, helper, util, broker, metadata, process, handle, context. Remove them unless a specific context justifies their use.

Even though overly long names are generally better than overly short ones, following these principles keeps code clear and easier to read, benefiting both teammates and your future self.

Commit Message Best Practice: The first line of a commit message should be on its own line because tools like GitHub display it separately, allowing quick browsing of history.

Linking to Defect Reports: Use issue tickets to track a defect or feature, providing a complete history of the change, including discussion and annotations. Most commits should be associated with a ticket, while isolated small changes may not need a separate ticket.

Rich commit messages and linked defect reports complement each other, offering context from different angles and helping anyone (including yourself) recall what was done weeks, months, or years ago.

Below is an advertisement for the book Continuous Delivery 2.0 :

Heavy Recommendation

《Continuous Delivery 2.0》

Silicon Valley top internet companies' product development methods.

In the next ten years, rapidly improve engineering productivity, build battle‑ready teams, and face fierce market competition.

This book is all you need~

Continuous Delivery 2.0: Business‑Driven DevOps Essentials

Scan to purchase

This book redefines continuous delivery, adds organizational management and architecture dimensions, and provides real‑world cases to interpret many principles and practices, discussing trade‑offs to quickly achieve organizational capability goals.

About the Author

Qiao Liang

Founder of Continuous Delivery 2.0

Focus on software enterprise organization management

Top DevOps expert

Author of Continuous Delivery 2.0, Continuous Delivery, Software Reflections

Follow the public account for more original works