diff --git a/builder/src/main/java/com/iluwatar/builder/App.java b/builder/src/main/java/com/iluwatar/builder/App.java index bcdbb8821850..b6131c3ab417 100644 --- a/builder/src/main/java/com/iluwatar/builder/App.java +++ b/builder/src/main/java/com/iluwatar/builder/App.java @@ -4,7 +4,20 @@ /** * - * This is the Builder pattern variation as described by Joshua Bloch in + * The intention of the Builder pattern is to find a solution to the telescoping + * constructor anti-pattern. The telescoping constructor anti-pattern occurs when the + * increase of object constructor parameter combination leads to an exponential list + * of constructors. Instead of using numerous constructors, the builder pattern uses + * another object, a builder, that receives each initialization parameter step by step + * and then returns the resulting constructed object at once. + *

+ * The Builder pattern has another benefit. It can be used for objects that contain + * flat data (html code, SQL query, X.509 certificate...), that is to say, data that + * can't be easily edited. This type of data cannot be edited step by step and must + * be edited at once. The best way to construct such an object is to use a builder + * class. + *

+ * In this example we have the Builder pattern variation as described by Joshua Bloch in * Effective Java 2nd Edition. *

* We want to build {@link Hero} objects, but its construction is complex because of the