From 6f91301cb07e6999635d651a1b85d49fee4b2f7c Mon Sep 17 00:00:00 2001
From: "Brian R. Bondy" <netzen@gmail.com>
Date: Thu, 7 May 2026 06:52:19 -0400
Subject: [PATCH] Add best practice CS-070: Use *.mojom-forward.h in headers
 (#36219)

Add best practice: Use *.mojom-forward.h in headers

CS-070: prefer the auto-generated *.mojom-forward.h over the full
*.mojom.h bindings when a header only references mojom types as
pointers, references, or function parameters. Reduces compile times
and transitive dependencies.

Source: PR #35622 review comment by netzenbot.
---
 docs/best-practices/coding-standards.md | 37 +++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/docs/best-practices/coding-standards.md b/docs/best-practices/coding-standards.md
index 6328a3eaf77..78b208f4bb1 100644
--- a/docs/best-practices/coding-standards.md
+++ b/docs/best-practices/coding-standards.md
@@ -1139,3 +1139,40 @@ base::debug::ScopedCrashKeyString scoped_key(crash_key, state);
 ```
 
 See [Chromium C++ style guide](https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/c++/c++.md).
+
+---
+
+<a id="CS-070"></a>
+
+## ✅ Use `*.mojom-forward.h` in Headers When Only Forward Declarations Are Needed
+
+**When a header only references mojom types as pointers, references, or function parameters, include the auto-generated `*.mojom-forward.h` instead of the full `*.mojom.h` bindings.** The forward header declares all types from the mojom file without pulling in the full bindings, which reduces compile times and transitive dependencies. Move the full `*.mojom.h` include to the `.cc` file where the types are actually used.
+
+```cpp
+// ❌ WRONG - full mojom bindings in header for forward-declared usage only
+// prefs_registration.h
+#include "brave/components/containers/core/mojom/containers.mojom.h"
+
+namespace containers {
+void RegisterProfilePrefs(
+    user_prefs::PrefRegistrySyncable* registry,
+    const std::vector<mojom::ContainerPtr>& default_containers);
+}
+
+// ✅ CORRECT - forward header in .h, full include in .cc
+// prefs_registration.h
+#include "brave/components/containers/core/mojom/containers.mojom-forward.h"
+
+namespace containers {
+void RegisterProfilePrefs(
+    user_prefs::PrefRegistrySyncable* registry,
+    const std::vector<mojom::ContainerPtr>& default_containers);
+}
+
+// prefs_registration.cc
+#include "brave/components/containers/core/mojom/containers.mojom.h"
+```
+
+This is a mojom-specific application of [CS-014](#CS-014). The `*.mojom-forward.h` is auto-generated alongside the full bindings — every mojom target produces it.
+
+---