a client-server relationship
| Abstract: The dynamic nature of refactoring often makes it difficult to communicate refactoring ideas with other team members. The refactoring thumbnails, proposed in this article, provide a means to explain the evolution of a design as a sequence of high-level refactorings. |
One of the prerequisites for refactoring towards a more coherent design is a shared design vision among team members. A shared vision sets the target for further refactoring effort thereby leading to an almost natural convergence among the individually refactored design elements. In contrast, lack of a shared design vision many times leads to design elements that may have be optimally factored locally but where overall coherence is absent at the higher layers.
In order to obtain a shared vision team members need to be able to effectively communicate their refactoring ideas. When able to do so team members can talk through their design ideas and make informed decisions about the strategy that will be followed in the further evolution of the design. However, expressing one 's refactoring ideas to other team members can be difficult, especially because the dynamics of the envisioned evolution is not reflected in the code. Rather, the code is a static snapshot of a design within a certain stage of it's evolution.
Using drawings is often helpful when explaining an idea. A refactoring thumbnail is a drawing that is intended to express a refactoring idea. Refactoring thumbnails look a little like small class diagrams. They're different from class diagrams in that we less care about the exact semantics. Also, in order to be able to convey refactoring ideas quickly, refactoring thumbnails are kept small and focused. As such refactoring thumbnails allow us to zoom in on the interesting parts of a design within the context of a particular refactoring while omitting the irrelevant parts.
Refactoring thumbnails, however are not refactorings. Refactoring thumbnails are intended to convey a refactoring idea rather than providing a detailed mechanics the way refactorings do. Refactoring thumbnails merely set the target. Once set we will use refactorings to get there.
At time of writing the refactoring thumbnail idea is still immature and much remains to be explored. The following sections give an overview of the ideas that have been identified so far.
A refactoring thumbnail is a small informal class diagram that is used to communicate a specific property of a given design. Being informal, refactoring thumbnails allow to sketch the aspect we want to focus at quickly without the overhead of a full-fledged UML class diagram.
When used in thumbnail refactorings or evolution charts a refactoring thumbnail allows us to focus on the evolving feature and leaving out the irrelevant parts. The thumbnail below shows a client server relationship.
a client-server relationship
A thumbnail refactoring is a high-level refactoring that is described in pattern form. A thumbnail refactoring is referenced by a name that summarizes the refactoring idea. The body of a thumbnail refactoring consists out of a problem solution pair that has been formulated both textually and visually. A thumbnail refactoring also includes a context section that further discusses the benefits and drawbacks for the given high-level refactoring, mentions alternatives and refers to the actual refactorings that can be used for implementation of the thumbnail refactoring. The example below shows Move Feature as a thumbnail refactoring.
a thumbnail refactoring
An evolution chart is a sketch that presents the evolution of a design as a sequence of thumbnail refactorings. The power of evolution charts is that they allow to sketch the general idea quickly. However by themselves they are barely sufficient to explain a refactoring idea within the context of a given design. Rather than expressing the refactoring idea themselves the charts provide something to point and look at while the full story of a refactoring is being told.
Depending on the level of design a refactoring is being explained, the level of detail of an evolution chart may vary. Team members that already have a shared design vision will generally need less detail and may omit certain thumbnails. A maximally detailed evolution chart will show each of the individual thumbnail refactorings. The example below shows Move Feature as an evolution chart.
an evolution chart
Refactorings and refactoring thumbnails are similar in that both describe the evolution of an existing codebase. However, by intent refactorings and refactoring thumbnails are different. Refactorings document how code can be evolved safely by means of a detailed mechanics. In contrast, thumbnail refactorings document recurring strategic choices we make while refactoring. Thumbnail refactorings help us deciding where to go, while refactorings provide a detailed mechanics how to get there.
Refactoring thumbnails are intended as a means for developers to communicate their design ideas. We've discussed three forms where thumbnails can be useful: as informal diagram in a design discussion; as a problem / solution pair within a thumbnail refactoring; and finally, as a sequence of design stages within an evolution chart.