Follow Google's lead with programming style guides

Code style rules and guidance

Google employs, by Schwartz's count, more than 30,000 software engineers with wide variations in skill, specialties and background. Together, they create tens of thousands of daily code submissions and billions of lines of code -- some of which will run for decades. Without a coding style guide, individual preferences make the codebases difficult -- if not impossible -- to understand and manage efficiently.

Code might be written only once, but it gets read many times. Google strives to have in-house code be understandable by all engineers who read it, not just those who contribute to it.

A style guide tells a developer how to work with a particular programming language. Programming style guides are composed of rules and guidance. Rules are mandates, with very few exceptions, enforceable throughout the entire IT organization. Rules make good and bad programming behavior explicit. Guidance is a recommended practice or strategy. Guidance allows for more leeway than rules.

Purchase your copy of
Software Engineering
at Google by clicking
on the image above.

A coding style guide might inform programmers on such issues as acceptable naming conventions, how to store source files, and code format. Some rules border on the mundane, but they collectively serve larger organizational goals. For example, rules ensure developers write code in a way that minimizes the applications' memory footprint. A programming style guide can also set the course for easy adoption of new language features, or simply maintain consistency across many teams and projects.

Code consistency primarily pays off in readability. When code is consistent and readable across the organization, Schwartz advises, engineers see these benefits:

• ability to focus on what's getting done, rather than the minutiae of how it's coded;
• quick understanding of any codebase through familiar interfaces and formats;
• simpler scaling and implementation of automation; and
• easier change, such as product ownership transfers, new personnel onboarding and code handoffs.

"Consistency is what enables any engineer to jump into an unfamiliar part of the codebase and get to work fairly quickly," Schwartz writes. "A local project can have its unique personality, but its tools are the same, its technique are the same, its libraries are the same, and it all Just Works."

Style priorities and exceptions

Code style guides do reduce developer flexibility and creativity. For example, the Google coding style guide might restrict a Python expert from using new features in the language. The aim is to make code practices equal for the Python guru, the inexperienced developer and the site reliability engineer. Complex code constructs can lead to misuse and defects.

Style guides can establish rules for comments that explain what the code does, especially for complex code. Google implements style guide rules for both documentation comments -- inserted at the beginning of a file/class/function -- and implementation comments spread throughout the code. These comments provide explicit evidence of the code's intended behavior, stating the purpose and logic of a class or function.

It can take time for a rule or guidance to be accepted as a standard, especially in a large, multilevel software engineering organization. Google implements a hierarchy for its style guides and rules. Local teams can adapt and implement a rule more quickly than the overall organization. Make team rules a priority, Schwartz recommends. Keep in mind standards accepted by external communities too, such as contributors to an open source project. External developers might offer more expertise for lesser-known languages. The project scope should factor into the priority set for rules.

"If conventions already exist, it is usually a good idea for an organization to be consistent with the outside world," Schwartz writes. "For small, self-contained, and short-lived efforts, it likely won't make a difference; internal consistency matters more than anything happening outside the project's limited scope."

Exceptions to established rules and guidance are acceptable, as long as there's a reason. For example, breaking a rule might solve a unique practical challenge or offer a substantive optimization benefit.

"Performance matters," Schwartz writes. "Sometimes, even if it means sacrificing consistency or readability, it just makes sense to accommodate performance optimizations." But performance isn't the only exception. "Interoperability also matters. Code that is designed to work with specific non-Google pieces might do better if tailored for its target."

Types of style rules

Not all code rules are alike, and they can serve different goals. Schwartz details three rough categories of code rules:

• rules to avoid dangers
• rules to enforce best practices
• rules to ensure consistency

When you create rules to avoid dangers, call out constructs to avoid and specify how to use certain vocabulary types. "We specifically include rulings on the hard-to-use and the hard-to-use-correctly -- some language features have nuanced usage patterns that might not be intuitive or easy to apply properly, causing subtle bugs to creep in," Schwartz writes.

Rules to enforce best practices include conventions for comments and how to structure source files. These efforts keep a codebase maintainable. Also, the organization can define how to use language features as they mature, even if they're barred initially. "As adoption spreads, engineers wanting to use the new features in different ways discuss their examples with the style guide owners, asking for allowances to permit additional use cases beyond those covered by the initial restrictions."

Don't wait for an issue to arise to make a decision about code style. To ensure consistency, document code style rules proactively. Things like naming conventions, indent spacing and ordered import might not affect software functionality, but they should be consistent and clear throughout the engineering teams. "By choosing one [style], we've dropped out of the endless debate cycle and can just move on."

Editor's note: This information is from Software Engineering at Google, curated by Titus Winters, Tom Manshreck and Hyrum Wright, published by O'Reilly Media, March 17, 2020, ISBN: 9781492082798.