Add style guide rule about paired .h and .cc files

Bug: none
Notry: true
Change-Id: I26074f1decd81bae3c1045df5060c0c507c38a2d
Reviewed-on: https://webrtc-review.googlesource.com/59141
Commit-Queue: Karl Wiberg <kwiberg@webrtc.org>
Reviewed-by: Mirko Bonadei <mbonadei@webrtc.org>
Reviewed-by: Niels Moller <nisse@webrtc.org>
Reviewed-by: Danil Chapovalov <danilchap@webrtc.org>
Cr-Commit-Position: refs/heads/master@{#22424}

style-guide.md

@@ -20,6 +20,29 @@ both.
 [chr-style]: https://chromium.googlesource.com/chromium/src/+/HEAD/styleguide/c++/c++.md
 [goog-style]: https://google.github.io/styleguide/cppguide.html
 
+### <a name="h-cc-pairs"></a>`.h` and `.cc` files come in pairs
+
+`.h` and `.cc` files should come in pairs, with the same name (except
+for the file type suffix), in the same directory, in the same build
+target.
+
+* If a declaration in `path/to/foo.h` has a definition in some `.cc`
+  file, it should be in `path/to/foo.cc`.
+* If a definition in `path/to/foo.cc` file has a declaration in some
+  `.h` file, it should be in `path/to/foo.h`.
+* Omit the `.cc` file if it would have been empty, but still list the
+  `.h` file in a build target.
+* Omit the `.h` file if it would have been empty. (This can happen
+  with unit test `.cc` files, and with `.cc` files that define
+  `main`.)
+
+This makes the source code easier to navigate and organize, and
+precludes some questionable build system practices such as having
+build targets that don’t pull in definitions for everything they
+declare.
+
+[Examples and exceptions](style-guide/h-cc-pairs.md).
+
 ### ArrayView
 
 When passing an array of values to a function, use `rtc::ArrayView`

style-guide/OWNERS

@@ -0,0 +1,2 @@
+danilchap@webrtc.org
+kwiberg@webrtc.org

style-guide/h-cc-pairs.md

@@ -0,0 +1,29 @@
+# `.h` and `.cc` files come in pairs
+
+This is an overflow page for [this](../style-guide.md#h-cc-pairs)
+style rule.
+
+## Example violations
+
+Example violations, which should be avoided in new code:
+
+* Declarations in `path/to/include/foo.h`, definitions in
+  `path/to/source/foo.cc`. **Fix:** The `.h` and `.cc` files should be
+  in the same directory.
+* Declarations in `foo.h`, definitions in both `foo_bar.cc` and
+  `foo_baz.cc`. **Fix:** The `.h` and `.cc` files should come in
+  pairs, so either split `foo.h` into `foo_bar.h` and `foo_baz.h`, or
+  merge `foo_bar.cc` and `foo_baz.cc` into `foo.cc`.
+
+## Exception for platform-specific code
+
+If the functions in a header file need different implementations for
+different platforms, we allow the following arrangement:
+
+* Declarations in `foo.h`.
+* A complete set of matching definitions in `foo_win.cc`, another
+  complete set of matching definitions in `foo_mac.cc`, and so on.
+* As per the main rule, these files should all be in the same
+  directory and in the same build target. The build target should use
+  platform conditionals to ensure that exactly one of the `.cc` files
+  are included.