Update README.md

facade/README.md

@@ -10,14 +10,18 @@ tags:
 ---
 
 ## Intent
-Provide a unified interface to a set of interfaces in a subsystem.
-Facade defines a higher-level interface that makes the subsystem easier to use.
+
+Provide a unified interface to a set of interfaces in a subsystem. Facade defines a higher-level 
+interface that makes the subsystem easier to use.
 
 ## Explanation
 
 Real world example
 
-> How does a goldmine work? "Well, the miners go down there and dig gold!" you say. That is what you believe because you are using a simple interface that goldmine provides on the outside, internally it has to do a lot of stuff to make it happen. This simple interface to the complex subsystem is a facade.
+> How does a goldmine work? "Well, the miners go down there and dig gold!" you say. That is what you 
+> believe because you are using a simple interface that goldmine provides on the outside, internally 
+> it has to do a lot of stuff to make it happen. This simple interface to the complex subsystem is a 
+> facade.
 
 In plain words
 
@@ -25,11 +29,13 @@ In plain words
 
 Wikipedia says
 
-> A facade is an object that provides a simplified interface to a larger body of code, such as a class library.
+> A facade is an object that provides a simplified interface to a larger body of code, such as a 
+> class library.
 
 **Programmatic Example**
 
-Taking our goldmine example from above. Here we have the dwarven mine worker hierarchy
+Let's take our goldmine example from above. Here we have the dwarven mine worker hierarchy. First
+there's a base class `DwarvenMineWorker`:
 
 ```java
 public abstract class DwarvenMineWorker {
@@ -87,7 +93,12 @@ public abstract class DwarvenMineWorker {
     GO_TO_SLEEP, WAKE_UP, GO_HOME, GO_TO_MINE, WORK
   }
 }
+```
 
+Then we have the concrete dwarf classes `DwarvenTunnelDigger`, `DwarvenGoldDigger` and 
+`DwarvenCartOperator`:
+
+```java
 public class DwarvenTunnelDigger extends DwarvenMineWorker {
 
   private static final Logger LOGGER = LoggerFactory.getLogger(DwarvenTunnelDigger.class);
@@ -135,7 +146,7 @@ public class DwarvenCartOperator extends DwarvenMineWorker {
 
 ```
 
-To operate all these goldmine workers we have the facade
+To operate all these goldmine workers we have the `DwarvenGoldmineFacade`:
 
 ```java
 public class DwarvenGoldmineFacade {
@@ -168,22 +179,27 @@ public class DwarvenGoldmineFacade {
 }
 ```
 
-Now to use the facade
+Now let's use the facade:
 
 ```java
-DwarvenGoldmineFacade facade = new DwarvenGoldmineFacade();
+var facade = new DwarvenGoldmineFacade();
 facade.startNewDay();
+facade.digOutGold();
+facade.endDay();
+```
+
+Program output:
+
+```java
 // Dwarf gold digger wakes up.
 // Dwarf gold digger goes to the mine.
 // Dwarf cart operator wakes up.
 // Dwarf cart operator goes to the mine.
 // Dwarven tunnel digger wakes up.
 // Dwarven tunnel digger goes to the mine.
-facade.digOutGold();
 // Dwarf gold digger digs for gold.
 // Dwarf cart operator moves gold chunks out of the mine.
 // Dwarven tunnel digger creates another promising tunnel.
-facade.endDay();
 // Dwarf gold digger goes home.
 // Dwarf gold digger goes to sleep.
 // Dwarf cart operator goes home.
@@ -193,14 +209,25 @@ facade.endDay();
 ```
 
 ## Class diagram
+
 ![alt text](./etc/facade.urm.png "Facade pattern class diagram")
 
 ## Applicability
+
 Use the Facade pattern when
 
-* you want to provide a simple interface to a complex subsystem. Subsystems often get more complex  as they evolve. Most patterns, when applied, result in more and smaller classes. This makes the subsystem more reusable and easier to customize, but it also becomes harder to use for clients that don't need to customize it. A facade can provide a simple default view of the subsystem that is good enough for most clients. Only clients needing more customizability will need to look beyond the facade.
-* there are many dependencies between clients and the implementation classes of an abstraction. Introduce a facade to decouple the subsystem from clients and other subsystems, thereby promoting subsystem independence and portability.
-* you want to layer your subsystems. Use a facade to define an entry point to each subsystem level. If subsystems are dependent, then you can simplify the dependencies between them by making them communicate with each other solely through their facades.
+* You want to provide a simple interface to a complex subsystem. Subsystems often get more complex 
+as they evolve. Most patterns, when applied, result in more and smaller classes. This makes the 
+subsystem more reusable and easier to customize, but it also becomes harder to use for clients that 
+don't need to customize it. A facade can provide a simple default view of the subsystem that is good 
+enough for most clients. Only clients needing more customization will need to look beyond the 
+facade.
+* There are many dependencies between clients and the implementation classes of an abstraction. 
+Introduce a facade to decouple the subsystem from clients and other subsystems, thereby promoting 
+subsystem independence and portability.
+* You want to layer your subsystems. Use a facade to define an entry point to each subsystem level. 
+If subsystems are dependent, then you can simplify the dependencies between them by making them 
+communicate with each other solely through their facades.
 
 ## Credits