BazelCon 2018 Day 2: Knowledge Transfer by Source Code

## Overview Offair, a software engineer at Google, presents on 'Knowledge Transfer by Source Code,' exploring how organizations can effectively share codebase knowledge using Google's open-source tools. The talk addresses two knowledge transfer modes: personalization (synchronous, one-on-one, unscalable) and codification (wikis, docs, code comments, scalable but maintenance-heavy). Google's solution combines both by simplifying systems and encoding knowledge directly into source code through Protocol Buffers, gRPC, and Bazel.

## Key Topics

**Simplification at Google** Google uses a unified approach internally: one style guide, one developer OS, one repository, one data format, one server communication protocol, and Bazel as the build tool. This standardization reduces friction and knowledge fragmentation.

**Protocol Buffers for Data Codification** Protocol Buffers serve as strongly-typed alternatives to JSON. Illustrated with the scenario of Newman encountering confusing field names (title vs. actual_title) due to backward compatibility constraints, Protocol Buffers enable field renaming while maintaining binary compatibility since field IDs—not names—are transmitted. The format automatically generates code and enums across all supported languages, eliminating manual synchronization between teams.

**gRPC for API Clarity** gRPC builds on Protocol Buffers to declaratively define server endpoints, requests, and responses. Instead of reverse-engineering APIs (as Fred must do to understand Becky's endpoint), developers receive auto-generated client and server code, encoding API contracts directly in the codebase.

**Bazel for Build Democratization** Bazel creates reproducible builds that eliminate environmental variance, enabling developers to help each other effectively (addressing the Jared/Jeffy scenario where Jeffy cannot reproduce Jared's compilation error). It simplifies tool sharing—developers share tools with colleagues in different languages without distributing binaries or managing multiple versions. Visibility controls manage cross-team dependencies without forcing repository silos.

**Lowering Barriers Across Disciplines** Bazel reduces friction between teams and languages. Patty, a Python developer, can contribute to JavaScript code without installing Gulp, npm, Webpack, and other tools if Bazel encodes the build configuration.

## Technical Details

- Protocol Buffer binary format compacts data by transmitting field IDs instead of field names, enabling field renames without breaking clients. - gRPC auto-generates client and server stubs, reducing manual API documentation burden. - Bazel's visibility attribute controls which code can be used by whom, encouraging explicit conversations about ownership and collaboration. - The Reviewer tool (briefly discussed) supports multi-repository code review with atomic commits across repositories, is hosting-agnostic (GitHub, GitLab, Bitbucket, Google Cloud Repositories), and handles mixed private/public repositories securely by running analysis locally without transmitting private code off-machine.

## Takeaways

1. **Encode Knowledge in Code**: Document APIs, data structures, and build requirements through language-native constructs rather than external wikis prone to becoming outdated. 2. **Standardize Foundations**: Use unified tools and protocols to reduce configuration burden and knowledge fragmentation. 3. **Design for Discoverability**: Ensure developers can understand and use APIs without consulting the original author. 4. **Enable Contribution Across Disciplines**: Lower barriers to contribution by providing tooling that abstracts environmental complexity. 5. **Explore Best Practices**: The speaker references the 'Startup OS' template repository demonstrating adoption of these technologies.