brave-core/docs/best_practices.md

Brave Browser Best Practices

This document is an index of best practices for the Brave Browser codebase, discovered from code reviews, test fixes, and development experience. Each section links to a detailed document.

Nala / Leo Design System

• Nala / Leo Design System - Icons (Android, WebUI, C++), Android color tokens, Leo component usage

Code & Architecture

• Architecture and Code Organization - Layering violations, dependency injection, factory patterns, pref management
• C++ Coding Standards - IWYU, naming conventions, CHECK vs DCHECK, style, comments, logging
• C++ Memory, Lifetime & Threading - Ownership, WeakPtr, Unretained, raw_ptr, KeyedService shutdown, threading
• C++ API Usage, Containers & Types - base utilities, containers, type safety, optional, span, callbacks
• Documentation - Inline comments, method docs, READMEs, keeping docs fresh, avoiding duplication
• Localization & String Resources - GRD/GRDP conventions, string descriptions, placeholders, UI text voice, i18n patterns
• Brave Style Guide - Voice, capitalization, punctuation, product naming, accessibility, privacy/security terms, product messaging
• Front-End (TypeScript/React) - Component props, spread args, XSS prevention
• Android (Java/Kotlin) - Activity/Fragment lifecycle, null safety, LazyHolder singletons, theme handling, Robolectric, bytecode patching, NullAway (@Nullable placement, @MonotonicNonNull, assert/assume patterns, destruction, view binders, Supplier variance, JNI nullness)
• chromium_src Overrides - Overrides vs patches, minimizing duplication, ChromiumImpl fallback
• Build System - BUILD.gn organization, buildflags, DEPS, GRD resources
• UI/Views - Desktop C++ views, view hierarchy, layout, styling
• Patches - Patch style, minimality, extensibility via defines/includes, GN patch patterns
• Plaster - Plaster patch configuration patterns and best practices
• iOS (Swift/ObjC/UIKit) - Swift idioms, SwiftUI, UIKit lifecycle, ObjC bridge, Tab architecture, chromium_src iOS overrides

Testing

• Async Testing Patterns - Root cause analysis, RunUntil, RunUntilIdle, nested run loops, TestFuture
• JavaScript Evaluation in Tests - MutationObserver, polling loops, isolated worlds, renderer setup
• Navigation and Timing - Same-document navigation, timeouts, page distillation
• Test Isolation and Specific Patterns - Fakes, API testing, HTTP request testing, throttle testing, Chromium patterns

Quick Checklist

Before writing async tests, verify:

• No RunLoop::RunUntilIdle() usage
• No EvalJs() or ExecJs() inside RunUntil() lambdas
• Using manual polling loops for JavaScript conditions
• Using base::test::RunUntil() only for C++ conditions
• Waiting for specific completion signals, not arbitrary timeouts
• Using isolated worlds (ISOLATED_WORLD_ID_BRAVE_INTERNAL) for test JS
• Per-resource expected values for HTTP request testing
• Large throttle windows for throttle behavior tests
• Proper observers for same-document navigation
• Testing public APIs, not implementation details
• Searched Chromium codebase for similar patterns
• Included Chromium code references in comments when following patterns
• Prefer event-driven JS (MutationObserver) over C++ polling for DOM changes

References

• Chromium Browser Design Principles - Feature scoping, modularity, UI patterns, lifetime management
• Chromium C++ Testing Best Practices
• Chromium C++ Style Guide
• Chromium Smart Pointer Guidelines
• Chromium Container Guidelines
• Chromium Componentization Cookbook