From fcea1f73522b7da68a3d15cfbcc2d3d57d8512c5 Mon Sep 17 00:00:00 2001 From: Pascal Berger Date: Wed, 20 Nov 2019 23:18:53 +0100 Subject: [PATCH] Use correct heading levels for TOC generation --- .../docs/getting-started/fundamentals.md | 32 +++++++++---------- docs/input/docs/getting-started/principles.md | 4 +-- .../getting-started/whystrategypattern.md | 2 +- docs/input/docs/usage/obtain.md | 2 +- 4 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/input/docs/getting-started/fundamentals.md b/docs/input/docs/getting-started/fundamentals.md index 5342eba..a2a5c66 100644 --- a/docs/input/docs/getting-started/fundamentals.md +++ b/docs/input/docs/getting-started/fundamentals.md @@ -4,14 +4,14 @@ Title: Fundamentals of strategy pattern Description: Apply code structure, make code readable and fulfill open/close and single responsibility principles using strategy pattern. --- -## Case study: The Switch Case Block +# Case study: The Switch Case Block A lot of documentation and tutorials exist explaining the implementation of the strategy pattern. For an overview see [Strategy pattern (wikipedia)], at least the chapter of [Strategy and open/closed principle] is recommended to read. The approach of this fundamentals article is to introduce and explain the concepts and reasons of strategy pattern based on a case study: The refactoring of a switch case block. Many code bases contain distinction of cases implemented by switch case blocks. Those implementations have numerous issues. -### Violation of open/close principle +## Violation of open/close principle See also [Open/close principle (wikipedia)]. An appropriate class design supports the enhancement of functionality (open for extension) without changing the class itself (closed for modification). Switch case blocks do not fulfill this principle. @@ -34,7 +34,7 @@ public void Foo(FooEnum fooEnum) If the FooEnum is extended by further enum values, the switch case block must be modified as well. -### Violation of single responsibility principle +## Violation of single responsibility principle See also [Single responsibility principle (wikipedia)]. The switch case block from the example above does two things. @@ -49,19 +49,19 @@ As a consequence two reasons exist to modify this method. Therefore the single responsibility principle is violated and consequently the reusability is limited. Neither the distinction of cases nor the code within the case blocks could be used separately. -### Maintainability +## Maintainability Most likely the above mentioned distinction of cases happens in multiple code areas. Each time the FooEnum is extended all those areas must be modified and extended as well. As a consequence effort increases. Without appropriate test coverage code stability decreases. This are the main reasons why distinction of cases should be centralized and separated from executing code. -### Readability and code structure +## Readability and code structure To fully understand the switch case block from the example above the whole block must be analyzed. Each case section can be freely implemented. The case section has no limitations and can access all members and variables within the method scope. The code has a lack of structure. -## Improvement: Use strategy +# Improvement: Use strategy As a first step the functionality of the case sections should be separated into classes. Those classes should be structured by implementing a common interface. @@ -120,35 +120,35 @@ public class Foo } ``` -### Improvements with strategy usage +## Improvements with strategy usage #### Single responsibility principle With the introduction of FooStrategyFactory the distinction of cases is moved into its own class and separated from execution logic in case blocks. This leads to higher chance of reuse. If other areas of code also need a distinction based on FooEnum, the FooStrategyFactory can be reused. -#### Maintainability +### Maintainability Because the switch case block of FooEnum is centralized by FooStrategyFactory, maintainability and code stability is improved. Enhancements on FooEnum affects only this single existing class (and the implementation of a new FooStrategy). -#### Readability and code structure +### Readability and code structure After the refactoring the original method became explicit, structured and focused on the Bar method call. -### Issues +## Issues -#### Violation of open/closed principle +### Violation of open/closed principle The strategy factory still consist of the switch case block. If the FooEnum is enhanced the GetStrategy method must still be modified as well. -#### Violation of single responsibility principle +### Violation of single responsibility principle Besides the strategy selection the implementation of the FooStrategyFactory has another responsibility: The instantiation of the strategy instance. This aspect should be separated and should have its own realization. There are third party libraries available for object instantiation. Commonly used are IoC-containers. With those containers the behaviour of object lifecycle (e.g. transient, singleton) can be declared and therefore delegated to those libraries. -## Improvement: Use generic strategy and and provider +# Improvement: Use generic strategy and and provider BBT.StrategyPattern defines an interface for declaration of strategies based on a generic type parameter. @@ -217,14 +217,14 @@ kernel.Bind().To(); kernel.Bind().To(); ``` -### Improvements with generic strategy and generic strategy provider usage +## Improvements with generic strategy and generic strategy provider usage -#### Open/closed principle +### Open/closed principle When FooEnum is enhanced, with the generic strategy provider, additional strategies can be added without modifying existing classes. As soon as the new strategies are registered in the IoC container, the provider is extended. -#### Single responsibility principle +### Single responsibility principle The generic provider has one single responsibility: Providing the requested strategy. How this strategy is instantiated is separated and handled be the strategy locator (i.e. IoC container). diff --git a/docs/input/docs/getting-started/principles.md b/docs/input/docs/getting-started/principles.md index 8d25c7b..3e068e0 100644 --- a/docs/input/docs/getting-started/principles.md +++ b/docs/input/docs/getting-started/principles.md @@ -10,13 +10,13 @@ The library introduces an `IGenericStrategy` which needs to be implemented fo The instances of the `IGenericStrategy` are managed by the `IGenericStrategyProvider` which resolves the correct implementation for the given criterion. The generic parameter acts as selection criterion and declares the responsibility of the specific strategy. -## Advantages +# Advantages * The generic strategy interface leads to more structured code. * Based on their generic type parameter, strategies are categorized and make their responsibility explicit. As a consequence this leads to higher chance of reuse and better readable code. * The implementation is driven by SOLID principles like open/closed, single responsibility and dependency inversion. For further explanations see [Fundamentals of strategy pattern]. -## Implementation details +# Implementation details * Introduces a generic strategy interface * The generic parameter represents the criterion for the selection of the specific strategy diff --git a/docs/input/docs/getting-started/whystrategypattern.md b/docs/input/docs/getting-started/whystrategypattern.md index 55de399..26595e5 100644 --- a/docs/input/docs/getting-started/whystrategypattern.md +++ b/docs/input/docs/getting-started/whystrategypattern.md @@ -6,7 +6,7 @@ Description: Introduction to BBT.StrategyPattern, what problems are solved and h BBT.StrategyPattern is a generic implementation of the strategy design pattern. -## Features +# Features * Support the usage of strategies with no need to implement specific strategy factories * Provide a generic strategy provider based on generics diff --git a/docs/input/docs/usage/obtain.md b/docs/input/docs/usage/obtain.md index 724450d..b26f449 100644 --- a/docs/input/docs/usage/obtain.md +++ b/docs/input/docs/usage/obtain.md @@ -4,7 +4,7 @@ Title: Obtain Description: Obtain BBT.StrategyPattern --- -## Nuget +# Nuget BBT.StrategyPattern is available as NuGet package. See [https://www.nuget.org/packages/BBT.StrategyPattern].