Merge pull request faif#213 from egens/add-tldr-comments

faif · web-flow · commit 2d4712a8d3c7 · 2017-12-08T19:07:48.000+01:00
Add tl;dr80 comment for most of the patterns.
diff --git a/behavioral/catalog.py b/behavioral/catalog.py
@@ -1,9 +1,11 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+
 """
 A class that uses different static function depending of a parameter passed in
 init. Note the use of a single dictionary instead of multiple conditions
 """
+
 __author__ = "Ibrahim Diop <ibrahim@sikilabs.com>"
 
 
diff --git a/behavioral/chain.py b/behavioral/chain.py
@@ -1,6 +1,9 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""http://www.dabeaz.com/coroutines/"""
+
+"""
+http://www.dabeaz.com/coroutines/
+"""
 
 from contextlib import contextmanager
 import os
diff --git a/behavioral/command.py b/behavioral/command.py
@@ -1,5 +1,11 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+
+"""
+*TL;DR80
+Encapsulates all information needed to perform an action or trigger an event.
+"""
+
 from __future__ import print_function
 import os
 from os.path import lexists
diff --git a/behavioral/iterator.py b/behavioral/iterator.py
@@ -1,8 +1,12 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+
 """
 http://ginstrom.com/scribbles/2007/10/08/design-patterns-python-style/
 Implementation of the iterator pattern with a generator
+
+*TL;DR80
+Traverses a container and accesses the container's elements.
 """
 
 from __future__ import print_function
diff --git a/behavioral/mediator.py b/behavioral/mediator.py
@@ -1,6 +1,12 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""http://web.archive.org/web/20120309135549/http://dpip.testingperspective.com/?p=28"""
+
+"""
+http://web.archive.org/web/20120309135549/http://dpip.testingperspective.com/?p=28
+
+*TL;DR80
+Encapsulates how a set of objects interact.
+"""
 
 import random
 import time
diff --git a/behavioral/memento.py b/behavioral/memento.py
@@ -1,6 +1,12 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""http://code.activestate.com/recipes/413838-memento-closure/"""
+
+"""
+http://code.activestate.com/recipes/413838-memento-closure/
+
+*TL;DR80
+Provides the ability to restore an object to its previous state.
+"""
 
 from copy import copy
 from copy import deepcopy
diff --git a/behavioral/observer.py b/behavioral/observer.py
@@ -1,7 +1,14 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+
+"""
+http://code.activestate.com/recipes/131499-observer-pattern/
+
+*TL;DR80
+Maintains a list of dependents and notifies them of any state changes.
+"""
+
 from __future__ import print_function
-"""http://code.activestate.com/recipes/131499-observer-pattern/"""
 
 
 class Subject(object):
diff --git a/behavioral/specification.py b/behavioral/specification.py
@@ -1,10 +1,11 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+
 """
 @author: Gordeev Andrey <gordeev.and.and@gmail.com>
 
-Specification provide recombination business logic by
-chaining together using boolean logic
+*TL;DR80
+Provides recombination business logic by chaining together using boolean logic.
 """
 
 from abc import abstractmethod
diff --git a/behavioral/state.py b/behavioral/state.py
@@ -1,8 +1,16 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""Implementation of the state pattern"""
 
-# http://ginstrom.com/scribbles/2007/10/08/design-patterns-python-style/
+"""
+Implementation of the state pattern
+
+http://ginstrom.com/scribbles/2007/10/08/design-patterns-python-style/
+
+*TL;DR80
+Implements state as a derived class of the state pattern interface.
+Implements state transitions by invoking methods from the pattern's superclass.
+"""
+
 from __future__ import print_function
 
 
diff --git a/behavioral/strategy.py b/behavioral/strategy.py
@@ -1,5 +1,6 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+
 """
 http://stackoverflow.com/questions/963965/how-is-this-strategy-pattern
  -written-in-python-the-sample-in-wikipedia
@@ -9,7 +10,11 @@
 http://en.wikipedia.org/wiki/Strategy_pattern), however Python supports
 higher-order functions and allows us to have only one class and inject
 functions into it's instances, as shown in this example.
+
+*TL;DR80
+Enables selecting an algorithm at runtime.
 """
+
 import types
 
 
diff --git a/behavioral/template.py b/behavioral/template.py
@@ -1,8 +1,14 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
-"""http://ginstrom.com/scribbles/2007/10/08/design-patterns-python-style/
 
-An example of the Template pattern in Python"""
+"""
+http://ginstrom.com/scribbles/2007/10/08/design-patterns-python-style/
+
+An example of the Template pattern in Python
+
+*TL;DR80
+Defines the skeleton of an algorithm, deferring steps to subclasses.
+"""
 
 ingredients = "spam eggs apple"
 line = '-' * 10
diff --git a/behavioral/visitor.py b/behavioral/visitor.py
@@ -1,7 +1,11 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+
 """
 http://peter-hoffmann.com/2010/extrinsic-visitor-pattern-python-inheritance.html
+
+*TL;DR80
+Separates an algorithm from an object structure on which it operates.
 """
 
 
diff --git a/creational/abstract_factory.py b/creational/abstract_factory.py
@@ -26,6 +26,8 @@
 https://sourcemaking.com/design_patterns/abstract_factory
 http://ginstrom.com/scribbles/2007/10/08/design-patterns-python-style/
 
+*TL;DR80
+Provides a way to encapsulate a group of individual factories.
 """
 
 
diff --git a/creational/borg.py b/creational/borg.py
@@ -36,6 +36,8 @@
 *References:
 https://fkromer.github.io/python-pattern-references/design/#singleton
 
+*TL;DR80
+Provides singletone-like behavior sharing state between instances.
 """
 
 
diff --git a/creational/builder.py b/creational/builder.py
@@ -24,6 +24,8 @@
 *References:
 https://sourcemaking.com/design_patterns/builder
 
+*TL;DR80
+Decouples the creation of a complex object and its representation.
 """
 
 
diff --git a/creational/factory_method.py b/creational/factory_method.py
@@ -28,6 +28,8 @@
 https://fkromer.github.io/python-pattern-references/design/#factory-method
 https://sourcemaking.com/design_patterns/factory_method
 
+*TL;DR80
+Creates objects without having to specify the exact class.
 """
 
 
diff --git a/creational/lazy_evaluation.py b/creational/lazy_evaluation.py
@@ -6,7 +6,7 @@
 
 https://en.wikipedia.org/wiki/Lazy_evaluation
 
-References:
+*References:
 bottle
 https://github.com/bottlepy/bottle/blob/cafc15419cbb4a6cb748e6ecdccf92893bb25ce5/bottle.py#L270
 django
@@ -17,6 +17,9 @@
 https://github.com/Pylons/pyramid/blob/7909e9503cdfc6f6e84d2c7ace1d3c03ca1d8b73/pyramid/decorator.py#L4
 werkzeug
 https://github.com/pallets/werkzeug/blob/5a2bf35441006d832ab1ed5a31963cbc366c99ac/werkzeug/utils.py#L35
+
+*TL;DR80
+Delays the eval of an expr until its value is needed and avoids repeated evals.
 """
 
 from __future__ import print_function
diff --git a/creational/pool.py b/creational/pool.py
@@ -26,6 +26,9 @@
 *References:
 http://stackoverflow.com/questions/1514120/python-implementation-of-the-object-pool-design-pattern
 https://sourcemaking.com/design_patterns/object_pool
+
+*TL;DR80
+Stores a set of initialized objects kept ready to use.
 """
 
 
diff --git a/creational/prototype.py b/creational/prototype.py
@@ -1,6 +1,11 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+"""
+*TL;DR80
+Creates new object instances by cloning prototype.
+"""
+
 
 class Prototype(object):
 
diff --git a/fundamental/delegation_pattern.py b/fundamental/delegation_pattern.py
@@ -4,6 +4,9 @@
 """
 Reference: https://en.wikipedia.org/wiki/Delegation_pattern
 Author: https://github.com/IuryAlves
+
+*TL;DR80
+Allows object composition to achieve the same code reuse as inheritance.
 """
 
 
diff --git a/other/graph_search.py b/other/graph_search.py
@@ -1,6 +1,7 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+""
 
 class GraphSearch:
 
diff --git a/structural/3-tier.py b/structural/3-tier.py
@@ -1,6 +1,11 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
+"""
+*TL;DR80
+Separates presentation, application processing, and data management functions.
+"""
+
 
 class Data(object):
     """ Data Store Class """
@@ -69,7 +74,7 @@ def main():
 # cheese
 # eggs
 # milk
-# 
+#
 # (Fetching from Data Store)
 # PRODUCT INFORMATION:
 # Name: Cheese, Price: 2.00, Quantity: 10
diff --git a/structural/adapter.py b/structural/adapter.py
@@ -1,5 +1,6 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
+
 """
 *What is this pattern about?
 The Adapter pattern provides a different interface for a class. We can
@@ -25,6 +26,9 @@
 http://ginstrom.com/scribbles/2008/11/06/generic-adapter-class-in-python/
 https://sourcemaking.com/design_patterns/adapter
 http://python-3-patterns-idioms-test.readthedocs.io/en/latest/ChangeInterface.html#adapter
+
+*TL;DR80
+Allows the interface of an existing class to be used as another interface.
 """
 
 
diff --git a/structural/bridge.py b/structural/bridge.py
@@ -1,7 +1,13 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-"""http://en.wikibooks.org/wiki/Computer_Science_Design_Patterns/Bridge_Pattern#Python"""
+"""
+*References:
+http://en.wikibooks.org/wiki/Computer_Science_Design_Patterns/Bridge_Pattern#Python
+
+*TL;DR80
+Decouples an abstraction from its implementation.
+"""
 
 
 # ConcreteImplementor 1/2
diff --git a/structural/composite.py b/structural/composite.py
@@ -5,25 +5,28 @@
 *What is this pattern about?
 The composite pattern describes a group of objects that is treated the
 same way as a single instance of the same type of object. The intent of
-a composite is to "compose" objects into tree structures to represent 
+a composite is to "compose" objects into tree structures to represent
 part-whole hierarchies. Implementing the composite pattern lets clients
 treat individual objects and compositions uniformly.
 
 *What does this example do?
-The example implements a graphic class，which can be either an ellipse 
-or a composition of several graphics. Every graphic can be printed. 
+The example implements a graphic class，which can be either an ellipse
+or a composition of several graphics. Every graphic can be printed.
 
 *Where is the pattern used practically?
-In graphics editors a shape can be basic or complex. An example of a 
+In graphics editors a shape can be basic or complex. An example of a
 simple shape is a line, where a complex shape is a rectangle which is
 made of four line objects. Since shapes have many operations in common
-such as rendering the shape to screen, and since shapes follow a 
-part-whole hierarchy, composite pattern can be used to enable the 
+such as rendering the shape to screen, and since shapes follow a
+part-whole hierarchy, composite pattern can be used to enable the
 program to deal with all shapes uniformly.
 
 *References:
 https://en.wikipedia.org/wiki/Composite_pattern
 https://infinitescript.com/2014/10/the-23-gang-of-three-design-patterns/
+
+*TL;DR80
+Describes a group of objects that is treated as a single instance.
 """
 
 
diff --git a/structural/decorator.py b/structural/decorator.py
@@ -1,4 +1,6 @@
 #!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
 """
 *What is this pattern about?
 The Decorator pattern is used to dynamically add a new feature to an
@@ -20,6 +22,9 @@
 
 *References:
 https://sourcemaking.com/design_patterns/decorator
+
+*TL;DR80
+Adds behaviour to object without affecting its class.
 """
 
 
diff --git a/structural/facade.py b/structural/facade.py
@@ -34,8 +34,10 @@
 https://sourcemaking.com/design_patterns/facade
 https://fkromer.github.io/python-pattern-references/design/#facade
 http://python-3-patterns-idioms-test.readthedocs.io/en/latest/ChangeInterface.html#facade
-"""
 
+*TL;DR80
+Provides a simpler unified interface to a complex system.
+"""
 
 from __future__ import print_function
 import time
diff --git a/structural/flyweight.py b/structural/flyweight.py
@@ -1,7 +1,13 @@
 #!/usr/bin/env python
 # -*- coding: utf-8 -*-
 
-"""http://codesnipers.com/?q=python-flyweights"""
+"""
+*References:
+http://codesnipers.com/?q=python-flyweights
+
+*TL;DR80
+Minimizes memory usage by sharing data with other similar objects.
+"""
 
 import weakref
 
diff --git a/structural/front_controller.py b/structural/front_controller.py
diff --git a/structural/mvc.py b/structural/mvc.py
diff --git a/structural/proxy.py b/structural/proxy.py
