docs: update step builder

step-builder/README.md

@@ -3,103 +3,175 @@ title: Step Builder
 category: Creational
 language: en
 tag:
- - Instantiation
+    - Code simplification
+    - Domain
+    - Encapsulation
+    - Extensibility
+    - Instantiation
+    - Interface
 ---
 
-# Step Builder Pattern
+## Also known as
+
+* Fluent Builder
+
+## Intent
+
+Separate the construction of a complex object step-by-step, allowing an object to be built incrementally.
 
 ## Explanation
 
-The Step Builder pattern is a creational design pattern used to construct a complex object step by step. It provides a fluent interface to create an object with a large number of possible configurations, making the code more readable and reducing the need for multiple constructors or setter methods.
+Real-world example
 
-## Intent
+> Imagine a scenario where you are assembling a custom computer. The process involves several steps: selecting the CPU, choosing the motherboard, adding memory, picking a graphics card, and installing storage. Each step builds on the previous one, gradually creating a fully functional computer. This step-by-step assembly process mirrors the Step Builder design pattern, ensuring that each component is correctly chosen and installed in a structured manner, ultimately resulting in a custom-built computer that meets specific requirements and preferences.
-An extension of the Builder pattern that fully guides the user through the creation of the object with no chances of confusion.
-The user experience will be much more improved by the fact that he will only see the next step methods available, NO build method until is the right time to build the object.
 
-## Real World Example
+In plain words
 
-Imagine you are building a configuration object for a database connection. The connection has various optional parameters such as host, port, username, password, and others. Using the Step Builder pattern, you can set these parameters in a clean and readable way:
+> The Step Builder pattern constructs complex objects incrementally through a series of defined steps, ensuring clarity and flexibility in the creation process.
 
-```java
+Wikipedia says
-DatabaseConnection connection = new DatabaseConnection.Builder()
-    .setHost("localhost")
-    .setPort(3306)
-    .setUsername("user")
-    .setPassword("password")
-    .setSSL(true)
-    .build();
-```
 
-## In Plain Words
+> The Step Builder pattern is a variation of the Builder design pattern, designed to provide a flexible solution for constructing complex objects step-by-step. This pattern is particularly useful when an object requires multiple initialization steps, which can be done incrementally to ensure clarity and flexibility in the creation process.
-
-The Step Builder pattern allows you to construct complex objects by breaking down the construction process into a series of steps. Each step corresponds to setting a particular attribute or configuration option of the object. This results in more readable and maintainable code, especially when dealing with objects that have numerous configuration options.
-
-## Wikipedia Says
-
-According to Wikipedia, the Step Builder pattern is a creational design pattern in which an object is constructed step by step. It involves a dedicated 'director' class, which orchestrates the construction process through a series of 'builder' classes, each responsible for a specific aspect of the object's configuration. This pattern is particularly useful when dealing with objects that have a large number of optional parameters.
 
 ## Programmatic Example
 
-Assuming you have a class `Product` with several configurable attributes, a Step Builder for it might look like this:
+Sure, let's create a programmatic example of the Step Builder design pattern using the code from the `step-builder` module.
+
+## Step Builder Design Pattern
+
+The Step Builder pattern is an extension of the Builder pattern that guides the user through the creation of an object in a step-by-step manner. This pattern improves the user experience by only showing the next step methods available, and not showing the build method until it's the right time to build the object.
+
+### Class Diagram
+
+![Step Builder](./etc/step-builder.png "Step Builder")
+
+### Code Example
+
+Let's consider a `Character` class that has many attributes such as `name`, `fighterClass`, `wizardClass`, `weapon`, `spell`, and `abilities`.
 
 ```java
-public class Product {
+@Getter
-    private String name;
+@Setter
-    private double price;
+public class Character {
-    private int quantity;
 
-    // private constructor to force the use of the builder
+  private String name;
-    private Product(String name, double price, int quantity) {
+  private String fighterClass;
+  private String wizardClass;
+  private String weapon;
+  private String spell;
+  private List<String> abilities;
 
-        this.name = name;
+  public Character(String name) {
-        this.price = price;
+    this.name = name;
-        this.quantity = quantity;
+  }
 
-    }
+  // toString method...
+}
+```
 
-    public static class Builder {
+Creating an instance of this class can be complex due to the number of attributes. This is where the Step Builder pattern comes in handy.
-        private String name;
-        private double price;
-        private int quantity;
 
-        public Builder setName(String name) {
+We create a `CharacterStepBuilder` class that guides the user through the creation of a `Character` object.
-            this.name = name;
-            return this;
-        }
 
-        public Builder setPrice(double price) {
+```java
-            this.price = price;
+public class CharacterStepBuilder {
-            return this;
-        }
 
-        public Builder setQuantity(int quantity) {
+  // Builder steps and methods...
-            this.quantity = quantity;
-            return this;
-        }
 
-        public Product build() {
+  public static NameStep newBuilder() {
-            return new Product(name, price, quantity);
+    return new Steps();
-        }
+  }
-    }
+
+  // Steps implementation...
+}
+```
+
+The `CharacterStepBuilder` class defines a series of nested interfaces, each representing a step in the construction process. Each interface declares a method for the next step, guiding the user through the construction of a `Character` object.
+
+```java
+public interface NameStep {
+  ClassStep name(String name);
 }
 
-// Usage
+public interface ClassStep {
-Product product = new Product.Builder()
+  WeaponStep fighterClass(String fighterClass);
-    .setName("Example Product")
+  SpellStep wizardClass(String wizardClass);
-    .setPrice(29.99)
+}
-    .setQuantity(100)
+
+// More steps...
+```
+
+The `Steps` class implements all these interfaces and finally builds the `Character` object.
+
+```java
+private static class Steps implements NameStep, ClassStep, WeaponStep, SpellStep, BuildStep {
+
+  private String name;
+  private String fighterClass;
+  private String wizardClass;
+  private String weapon;
+  private String spell;
+  private List<String> abilities;
+
+  // Implement the methods for each step...
+
+  @Override
+  public Character build() {
+    return new Character(name, fighterClass, wizardClass, weapon, spell, abilities);
+  }
+}
+```
+
+Now, creating a `Character` object becomes a guided process:
+
+```java
+var warrior = CharacterStepBuilder
+    .newBuilder()
+    .name("Amberjill")
+    .fighterClass("Paladin")
+    .withWeapon("Sword")
+    .noAbilities()
     .build();
 ```
 
-This example demonstrates how you can use the Step Builder pattern to create a `Product` object with a customizable set of attributes. Each method in the builder corresponds to a step in the construction process.
+## Class diagram
+
+![Step Builder](./etc/step-builder.png "Step Builder")
 
 ## Applicability
-Use the Step Builder pattern when the algorithm for creating a complex object should be independent of the parts that make up the object and how they're assembled the construction process must allow different representations for the object that's constructed when in the process of constructing the order is important.
 
-## Another example with class diagram
+* When constructing an object that requires multiple initialization steps.
-![alt text](./etc/step-builder.png "Step Builder")
+* When object construction is complex and involves many parameters.
+* When you want to provide a clear, readable, and maintainable way to construct an object in a step-by-step manner.
 
+## Known Uses
+
+* Complex configuration settings in Java applications.
+* Constructing objects for database records with multiple fields.
+* Building UI elements where each step configures a different part of the interface.
+
+## Consequences
+
+Benefits:
+
+* Improves code readability and maintainability by providing a clear and concise way to construct objects.
+* Enhances flexibility in creating objects as it allows variations in the construction process.
+* Encourages immutability by separating the construction process from the object's representation.
+
+Trade-offs:
+
+* May result in more complex code due to the additional classes and interfaces required.
+* Can lead to verbose code when many steps are involved.
+
+## Related Patterns
+
+* [Builder](https://java-design-patterns.com/patterns/builder/): Both patterns help in constructing complex objects. Step Builder is a variation that emphasizes incremental step-by-step construction.
+* [Fluent Interface](https://java-design-patterns.com/patterns/fluentinterface/): Often used in conjunction with the Step Builder pattern to provide a fluent API for constructing objects.
+* [Factory Method](https://java-design-patterns.com/patterns/factory-method/): Sometimes used with the Step Builder pattern to encapsulate the creation logic of the builder itself.
 
 ## Credits
 
-* [Marco Castigliego - Step Builder](http://rdafbn.blogspot.co.uk/2012/07/step-builder-pattern_28.html)
+* [Clean Code: A Handbook of Agile Software Craftsmanship](https://amzn.to/3wRnjp5)
+* [Effective Java](https://amzn.to/4cGk2Jz)
+* [Design Patterns: Elements of Reusable Object-Oriented Software](https://amzn.to/3w0pvKI)
+* [Step Builder - Marco Castigliego](http://rdafbn.blogspot.co.uk/2012/07/step-builder-pattern_28.html)