docs/patterns/builder-and-parameter-bundle.md - chromium/src - Git at Google

 # The Builder & Parameter Bundle Patterns

 The builder and parameter bundle patterns allow for giving a class a lot of
 configuration options at compile time, while leaving the runtime API small and
 the runtime constraints clear.

 Suppose that you are implementing a new class C, which has a name, a color, a
 size, and a URL associated with it, along with a handful of boolean parameters,
 each of which default to false. All of these values should be set before the C
 is actually used for anything. That class might look like this:

     class C {
      public:
       // Invariant: none of the members can change after you call Init().
       void Init();

      private:
       const std::string name_;
       const gfx::Color color_;
       const gfx::Size size_;
       const GURL url_;

       const bool is_cool_ = false;
       const bool is_nice_ = false;
       const bool is_friendly = false;
     };

 There are three ways you might choose to make this class configurable:

 1. Have the constructor take initial values for all of these arguments, or even
    have several constructors which take different subsets of the arguments.
 2. Have the constructor take no arguments, and instead expose setters for all of
    these values, and enforce the invariant of DoStuff() some other way.
 3. Have the constructor take values for all the arguments with no sensible
    default, and expose setters for the values that do have sensible defaults.

 Most classes end up doing one of these, and have an API that looks roughly like
 this:

     class C {
      public:
       C(std::string name, gfx::Color color, gfx::Size size, GURL url);

       void Init();

       void set_is_cool(bool is_cool) { is_cool_ = is_cool; }
       void set_is_nice(bool is_nice) { is_nice_ = is_nice; }
       void set_is_friendly(bool is_friendly) { is_friendly_ = is_friendly; }

      private:
       ...
       // Note that these now have to be non-const, even though they are
       // logically const, because the setters are exposed to mutate them before
       // use.
       bool is_cool_;
       bool is_nice_;
       bool is_friendly_;
     };

 Your class is forced into either:

 * Exposing every configuration option as a constructor argument, or
 * Allowing some things that are configurable only at construction to be set
   any time after construction, with errors caught at runtime

 The builder pattern (and the parameter bundle pattern, a simpler relative) offer
 a way out of this bind.

 ## Parameter Bundles

 A parameter bundle is an object that encapsulates all the parameters to another
 method, often to a constructor. For example, we might structure our class C like
 this:

     class C {
      public:
       struct Params {
         std::string name;
         // ...
       };

       C(Params params);

      private:
       const std::string name_;
       // ...
     };

 As long as the params struct is well-structured this may be all you need, and it
 can often significantly simplify constructing complicated classes if callers are
 allowed to fill in only those parts of the param bundle that they care about.

 However, there's a problem: constructors are not allowed to fail in C++. That
 implies that it has to be impossible to *make* an invalid `C::Params`, because
 if we did pass such an invalid parameter bundle into `C::C()`, the constructor
 would have no way to signal failure. We really want to ensure that we can only
 get an instance of `C` that is configured in a valid way.

 We can do that by adding a factory function to C:

     class C {
      public:
       unique_ptr<C> Make(Params params);

      private:
       // Since this is private, we can assume Params was validated by the
       // factory function first.
       C(Params params);
     };

 But in the process, we've cluttered the public API of C up with a lot of the
 details about how one manufactures an instance of C. What if we could avoid
 doing that? Enter...

 ## The Builder Pattern

 The key idea here is that instead of defining a `C::Params` class, we define a
 `C::Builder` class, which knows how to configure and then construct a new
 instance of `C`. That might look like this:

     class C {
      public:
       class Builder;    // defined elsewhere

      private:
       friend class Builder;
       C(Builder builder);    // only called from C::Builder
     };

 and now our `Builder` class has an interface like this:

     class Builder {
      public:
       Builder();
       void set_name(std::string name);
       void set_color(gfx::Color color):
       // ...

       std::unique_ptr<C> Build();
     }

 To an extent, this is just a syntactic variation of the parameter bundle
 pattern, but it does allow for one really nice convenience technique. If,
 instead of returning void, we have our setters return a reference to the Builder
 object itself:

     class Builder {
      public:
       Builder();
       Builder& set_name(std::string name);
       Builder& set_color(gfx::Color color);
       // ...

       std::unique_ptr<C> Build();
     }

 then instead of writing this:

     C::Builder builder;
     builder.set_name(name);
     builder.set_color(color);
     auto c = builder.Build();

 we can write this:

     auto c = C::Builder().set_name(name)
                          .set_color(color)
                          .Build();

 which lets us avoid naming the temporary builder object.

 ## Parameter pattern only for optional parameters

 It's also possible to use a version of the parameter/builder pattern only for
 optional arguments. In this case we make use of `Params&` to be able to chain
 calls like `Params().set_foo().set_bar()`, but we may not have a Build() method.

 In the first example, this would be:

     class C {
      public:
       class Params {
        public:
         Params();

         Params& set_is_cool(bool is_cool) { is_cool_ = is_cool; return *this; }
         ...

         bool is_cool() const { return is_cool_; }
         ...

        private:
         bool is_cool_ = false;
         bool is_nice_ = false;
         bool is_friendly = false;
       };

       // Populates all fields. Optional fields take their values from `params`.
       C(std::string name, gfx::Color color, gfx::Size size, GURL url,
         Params params = Params());

      private:
       const std::string name_;
       const gfx::Color color_;
       const gfx::Size size_;
       const GURL url_;

       const bool is_cool_;
       const bool is_nice_;
       const bool is_friendly;
     };

 Doing so lets us construct an object without awareness of the optional `Params`
 argument:

     C("foo", ...)

 While making `C` objects with optional parameters readable and without
 temporary variables:

     C("foo", ..., Params().set_is_cool(true));

 ## Use This Pattern When

 * Your class has more than half a dozen or so configuration options, most of
   which should not be changed once the object is "in use"
 * Your class has invalid sets of configuration options that should be prohibited
 * Your class has complicated configuration options of any sort that want runtime
   checking (places you might have previously used the [bool Init()
   pattern](bool-init.md))

 ## Alternatives / See Also

 * Regular constructor parameters
 * Instance variables with public setters

 ## Examples in Chromium

 * [DialogModel::Builder](https://source.chromium.org/chromium/chromium/src/+/main:ui/base/models/dialog_model.h;drc=72186360334350c90b9b94515b3c82bea25e27ff;l=88)
 * [ChildThreadImpl::Builder](https://source.chromium.org/chromium/chromium/src/+/main:content/child/child_thread_impl.h;l=273?q=Builder%20file:%5C.h$%20-file:%5Ethird_party%2F&ss=chromium%2Fchromium%2Fsrc)
 * [TestingProfile::Builder](https://source.chromium.org/chromium/chromium/src/+/main:chrome/test/base/testing_profile.h;l=97?q=Builder%20file:%5C.h$%20-file:%5Ethird_party%2F&ss=chromium%2Fchromium%2Fsrc)
	# The Builder & Parameter Bundle Patterns

	The builder and parameter bundle patterns allow for giving a class a lot of
	configuration options at compile time, while leaving the runtime API small and
	the runtime constraints clear.

	Suppose that you are implementing a new class C, which has a name, a color, a
	size, and a URL associated with it, along with a handful of boolean parameters,
	each of which default to false. All of these values should be set before the C
	is actually used for anything. That class might look like this:

	class C {
	public:
	// Invariant: none of the members can change after you call Init().
	void Init();

	private:
	const std::string name_;
	const gfx::Color color_;
	const gfx::Size size_;
	const GURL url_;

	const bool is_cool_ = false;
	const bool is_nice_ = false;
	const bool is_friendly = false;
	};

	There are three ways you might choose to make this class configurable:

	1. Have the constructor take initial values for all of these arguments, or even
	have several constructors which take different subsets of the arguments.
	2. Have the constructor take no arguments, and instead expose setters for all of
	these values, and enforce the invariant of DoStuff() some other way.
	3. Have the constructor take values for all the arguments with no sensible
	default, and expose setters for the values that do have sensible defaults.

	Most classes end up doing one of these, and have an API that looks roughly like
	this:

	class C {
	public:
	C(std::string name, gfx::Color color, gfx::Size size, GURL url);

	void Init();

	void set_is_cool(bool is_cool) { is_cool_ = is_cool; }
	void set_is_nice(bool is_nice) { is_nice_ = is_nice; }
	void set_is_friendly(bool is_friendly) { is_friendly_ = is_friendly; }

	private:
	...
	// Note that these now have to be non-const, even though they are
	// logically const, because the setters are exposed to mutate them before
	// use.
	bool is_cool_;
	bool is_nice_;
	bool is_friendly_;
	};

	Your class is forced into either:

	* Exposing every configuration option as a constructor argument, or
	* Allowing some things that are configurable only at construction to be set
	any time after construction, with errors caught at runtime

	The builder pattern (and the parameter bundle pattern, a simpler relative) offer
	a way out of this bind.

	## Parameter Bundles

	A parameter bundle is an object that encapsulates all the parameters to another
	method, often to a constructor. For example, we might structure our class C like
	this:

	class C {
	public:
	struct Params {
	std::string name;
	// ...
	};

	C(Params params);

	private:
	const std::string name_;
	// ...
	};

	As long as the params struct is well-structured this may be all you need, and it
	can often significantly simplify constructing complicated classes if callers are
	allowed to fill in only those parts of the param bundle that they care about.

	However, there's a problem: constructors are not allowed to fail in C++. That
	implies that it has to be impossible to make an invalid `C::Params`, because
	if we did pass such an invalid parameter bundle into `C::C()`, the constructor
	would have no way to signal failure. We really want to ensure that we can only
	get an instance of `C` that is configured in a valid way.

	We can do that by adding a factory function to C:

	class C {
	public:
	unique_ptr<C> Make(Params params);

	private:
	// Since this is private, we can assume Params was validated by the
	// factory function first.
	C(Params params);
	};

	But in the process, we've cluttered the public API of C up with a lot of the
	details about how one manufactures an instance of C. What if we could avoid
	doing that? Enter...

	## The Builder Pattern

	The key idea here is that instead of defining a `C::Params` class, we define a
	`C::Builder` class, which knows how to configure and then construct a new
	instance of `C`. That might look like this:

	class C {
	public:
	class Builder; // defined elsewhere

	private:
	friend class Builder;
	C(Builder builder); // only called from C::Builder
	};

	and now our `Builder` class has an interface like this:

	class Builder {
	public:
	Builder();
	void set_name(std::string name);
	void set_color(gfx::Color color):
	// ...

	std::unique_ptr<C> Build();
	}

	To an extent, this is just a syntactic variation of the parameter bundle
	pattern, but it does allow for one really nice convenience technique. If,
	instead of returning void, we have our setters return a reference to the Builder
	object itself:

	class Builder {
	public:
	Builder();
	Builder& set_name(std::string name);
	Builder& set_color(gfx::Color color);
	// ...

	std::unique_ptr<C> Build();
	}

	then instead of writing this:

	C::Builder builder;
	builder.set_name(name);
	builder.set_color(color);
	auto c = builder.Build();

	we can write this:

	auto c = C::Builder().set_name(name)
	.set_color(color)
	.Build();

	which lets us avoid naming the temporary builder object.

	## Parameter pattern only for optional parameters

	It's also possible to use a version of the parameter/builder pattern only for
	optional arguments. In this case we make use of `Params&` to be able to chain
	calls like `Params().set_foo().set_bar()`, but we may not have a Build() method.

	In the first example, this would be:

	class C {
	public:
	class Params {
	public:
	Params();

	Params& set_is_cool(bool is_cool) { is_cool_ = is_cool; return *this; }
	...

	bool is_cool() const { return is_cool_; }
	...

	private:
	bool is_cool_ = false;
	bool is_nice_ = false;
	bool is_friendly = false;
	};

	// Populates all fields. Optional fields take their values from `params`.
	C(std::string name, gfx::Color color, gfx::Size size, GURL url,
	Params params = Params());

	private:
	const std::string name_;
	const gfx::Color color_;
	const gfx::Size size_;
	const GURL url_;

	const bool is_cool_;
	const bool is_nice_;
	const bool is_friendly;
	};

	Doing so lets us construct an object without awareness of the optional `Params`
	argument:

	C("foo", ...)

	While making `C` objects with optional parameters readable and without
	temporary variables:

	C("foo", ..., Params().set_is_cool(true));

	## Use This Pattern When

	* Your class has more than half a dozen or so configuration options, most of
	which should not be changed once the object is "in use"
	* Your class has invalid sets of configuration options that should be prohibited
	* Your class has complicated configuration options of any sort that want runtime
	checking (places you might have previously used the [bool Init()
	pattern](bool-init.md))

	## Alternatives / See Also

	* Regular constructor parameters
	* Instance variables with public setters

	## Examples in Chromium

	* [DialogModel::Builder](https://source.chromium.org/chromium/chromium/src/+/main:ui/base/models/dialog_model.h;drc=72186360334350c90b9b94515b3c82bea25e27ff;l=88)
	* [ChildThreadImpl::Builder](https://source.chromium.org/chromium/chromium/src/+/main:content/child/child_thread_impl.h;l=273?q=Builder%20file:%5C.h$%20-file:%5Ethird_party%2F&ss=chromium%2Fchromium%2Fsrc)
	* [TestingProfile::Builder](https://source.chromium.org/chromium/chromium/src/+/main:chrome/test/base/testing_profile.h;l=97?q=Builder%20file:%5C.h$%20-file:%5Ethird_party%2F&ss=chromium%2Fchromium%2Fsrc)