docs: document "domain lens" pattern

Bug: None
Change-Id: I43f3af3003d12d218140db9415df13b230e1e2e5
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2508324
Commit-Queue: Elly Fong-Jones <ellyjones@chromium.org>
Reviewed-by: Peter Kasting <pkasting@chromium.org>
Cr-Commit-Position: refs/heads/master@{#822720}

docs/patterns/domain-lens.md

+# The Domain Lens Pattern
+
+The Domain Lens Pattern exposes a specific, more restricted view of a
+complicated class, customized to the needs of a specific domain. The name comes
+from the metaphor of looking at a class "through a specific lens", which
+magnifies parts of the class and hides other parts. This helps decouple clients
+from the entire implementation of the complicated class.
+
+Here's an example. Suppose we have a class NetworkRequest:
+
+```c++
+class NetworkRequest {
+  // ... lots of state ...
+  size_t bytes_done() const;
+  size_t bytes_to_do() const;
+};
+```
+
+and suppose that we are implementing a UI component that displays the status of
+a download, which is backed by a NetworkRequest. We could implement that like:
+
+```c++
+class DownloadView : public NetworkRequestObserver {
+ public:
+  // Start displaying the status of the given network request.
+  DownloadView(NetworkRequest* request);
+
+  // NetworkRequestObserver:
+  void OnRequestProgress(NetworkRequest* request) override;
+};
+```
+
+But there are two problems with this:
+
+1. When testing DownloadView, we need an entire NetworkRequest, and it's not
+   clear which parts of the NetworkRequest need to be filled in for DownloadView
+   to work;
+2. If we are refactoring and adding a different class (say for example
+   `DiskFileRequest` for a load from local disk), that class must subclass
+   `NetworkRequest` for DownloadView to be usable with it, which usually
+   involves a lot of empty methods and stub data.
+
+Instead, we can define a domain-specific lens, containing only the subset of the
+data in `NetworkRequest` needed to display download progress, like this:
+
+```c++
+struct DownloadProgress {
+  base::FilePath destination;
+  size_t bytes_done;
+  size_t bytes_to_do;
+};
+```
+
+and two interfaces for receiving updates on that domain-specific lens:
+
+```c++
+class DownloadProgressObserver {
+ public:
+  void OnDownloadProgress(const DownloadProgress& progress);
+};
+
+class DownloadProgressProvider {
+ public:
+  void AddObserver(DownloadProgressObserver* observer);
+  void RemoveObserver(DownloadProgressObserver* observer);
+
+  DownloadProgress GetCurrentProgress() const;
+};
+```
+
+at which point `DownloadView` is:
+
+```c++
+class DownloadView : public DownloadProgressObserver {
+ public:
+  DownloadView(DownloadProgressProvider* provider);
+};
+```
+
+or perhaps, using a callback rather than an observer class:
+
+```c++
+using DownloadProgressCallback =
+    base::RepeatingCallback<void(const DownloadProgress& progress)>;
+
+class DownloadProgressProvider {
+ public:
+  base::CallbackList::Subscription
+      RegisterDownloadProgressCallback(DownloadProgressCallback callback);
+  DownloadProgress GetCurrentProgress();
+};
+
+class DownloadView {
+ public:
+  DownloadView(DownloadProgressProvider* provider);
+};
+```
+
+## When To Use A Domain Lens
+
+A domain lens makes sense when you have:
+
+* A complicated object with a lot of state
+* A well-defined domain or client class that makes use of part of that
+  complicated object
+
+A common use of domain lenses is to extract only the data needed to display an
+object into a separate type, to decouple the object from its display logic. One
+Chromium example of this is [TabRendererData], which encapsulates only the state
+of a Tab needed to draw that Tab somewhere, without providing access to the
+Tab's underlying webcontents or any methods for mutating it.
+
+Here's another hypothetical, to illustrate this pattern. We have a class
+[ProfileAttributesEntry], which contains a lot of different pieces of data about
+a Profile. We might define a type and a new method on `ProfileAttributes`,
+specifically for drawing the profile "chip" that can replace the app menu icon:
+
+```c++
+// Note that this is a separate top-level type from ProfileAttributes. One could
+// instead define this as a nested type ProfileAttributes::LensForChip or
+// something similar, but then any user of this domain lens would need to have
+// the declaration of ProfileAttributes visible as well, which would cause some
+// of the coupling we're trying to avoid in the first place.
+struct ProfileAttributesForChip {
+  gfx::ImageSkia icon;
+  std::string name;
+  ...
+};
+
+ProfileAttributesForChip ProfileAttributes::ForChip() {
+  ...
+}
+```
+
+and then have the profile chip code use a `ProfileAttributesForChip` instead of
+a `ProfileAttributes`.
+
+## When Not To Use A Domain Lens
+
+Domain lenses are easy to overuse. In general, any given client of a complicated
+class uses only a subset of that class's functionality, but that does not mean
+each client should have its own lens - that would cause a lot of extra lens
+types and tangle the code needlessly. This pattern always involves writing extra
+translation functions and adapters, so it should only be done when the decreased
+coupling is worth the extra code needed to implement the lens itself. Clients
+that don't have their own domain lens on an object can continue to use the
+object itself as usual.
+
+[TabRendererData]: ../../chrome/browser/ui/tabs/tab_renderer_data.h
+[ProfileAttributesEntry]: ../../chrome/browser/profiles/profile_attributes_entry.h