Design patterns are used as prescriptive advice to communicate, inform and help implement a “general solution to a design problem”. They generally aim to be efficient by encapsulating experience and forethought into a concise representation. (The Open University, 2020a[1] )

An important consideration is the impact of effective documentation for design patterns, particularly in existing software solutions and specifically how their different representations affect the understandability of any source-code they are contained in.

I selected ‘Documenting Design-Pattern Instances: A Family of Experiments on Source-Code Comprehensibility’ byScanniello et al. (2015)[2] because it investigates how different provided formats or representations of design pattern documentation affect the understandability of source code.

Furthermore, while it is largely considered that Design patterns are important and useful there remains no uniform way share and transmit, describe and transform them in a flexible way - let alone choose on how best to represent them.

I also selected the paper ‘Towards design pattern definition language’ by Khwaja and Alshayeb (2013)[3] as it discusses a meta-representation to describe design patterns in a universal way.

Lastly, while design patterns are useful, they are inherently composed of dependencies which may aid in the propagation of software change. It is thus important to discuss the effects that design patterns have on coupling and change propagation in code that uses them.

It is for this reason I choose the paper, ‘Evaluating the impact of design pattern and anti-pattern dependencies on changes and faults’ byJaafar et al. (2016)[4] because it investigates the effects of such coupling i.e. the “measure of the dependency between classes” which are inherent in design-patterns and specifically on the propagation of change and of faults in the source code. (The Open University, 2020b[5] )

Selected Articles:

Jaafar, F., Guéhéneuc, Y.-G., Hamel, S., Khomh, F., Zulkernine, M., 2016. Evaluating the impact of design pattern and anti-pattern dependencies on changes and faults. Empirical Software Engineering 21, 896–931.

Khwaja, S., Alshayeb, M., 2013. Towards design pattern definition language. Software: Practice and Experience 43, 747–757.

Scanniello, G., Gravino, C., Risi, M., Tortora, G., Dodero, G., 2015. Documenting Design-Pattern Instances: A Family of Experiments on Source-Code Comprehensibility. ACM Transactions on Software Engineering and Methodology (TOSEM) 24, 1–35.

Article summaries:

Scanniello et al. (2015) investigate how the representation of design patterns may benefit the understandability of source code.

The authors highlight previous studies indicating the usefulness of documenting design patterns to aid understanding but note the specific lack of studies around the recognition of benefits of different kinds/representation.

This study is an extension of their own original experiment which then primarily focused on professional developers and which concluded that using graphical and textual forms of documentation positively aided source code comprehensibility.

This new study represents a variation of the original study, with a more diverse and varying degree of experience within participants groups (Bachelor through to PHD) all within the software engineering discipline along with professional developers as in the original study.

They set up controlled tests for participants to establish how the comprehension of some non-trivial source code is affected by the use of either textual, graphical (UML) or no documentation (source only) about the design patterns that underlie the source code. They designed and defined qualitative metrics and a questionnaire to assess comprehension, with questions based on recommendations by a previous, independent study by Sillito et al., (2008).

They use updated analysis, three new experiments and the inclusion of developer’s experiences/thoughts of the comprehension questionnaire.

The authors identify and define the notion of comprehension and how to assess it - based on Moderator (that which affects quality of comprehension) and Affected variables (the effect quality comprehension has). The variables are described with respect to those affecting source code comprehension namely time and precision which help formulate a unique ‘correctness of understanding’ qualitative metric. This is used to evaluate performance/quality of understanding.

Through a post experiment survey, measures of participants’ answer-confidence level, perceived difficulty and main source of information used in answering questions were evaluated. As too are the participants experiences of the tasks including its format, views of time restriction, clarity of task objectives and assessment of the amount of time spend analysing the source code.  

The results of the analysis of the comprehensibility questionnaire suggested that documentation of pattern instances positively aids in correctness of understanding as opposed to no documentation. Furthermore, participants’ experience level has a statistically significant effect on how well provided documentation (if any) was used.

Analysis of these post-experiment results suggest that more experienced participants use documentation better than those less experienced and that the source code was the main source of information in answering the comprehension questionnaire. Additionally, participants were more confident in level of understanding when referencing primarily the source code to inform their judgements. Feedback provided in this post-experiment questionnaire showed participants generally agreed on the format, time given and clarify of tasks

 Further analysis revealed, crucially, that improvements to ‘correctness in understanding’ is directly proportional to being able to correctly identify design patterns in source code but some “participants believed that a different kind of documentation could better fit comprehensibility”. (Scanniello et al., 2015)

 Khwaja and Alshayeb (2013) discusses a meta-representation to describe design patterns in a universal, portable and flexible way, which has implications for generating new representations of design pattern documentation:

The authors identify design patterns as widely used in software development, including as a communications aid amongst developers and that there are various existing representations. The paper’s aim is defined as the specification and definition of a new uniform pattern representation, based on XML that can be used for creating and sharing an unambiguous description of a design pattern in a flexible and extensible format called Design Pattern Definition Language (DPDL)

 The authors explain that sharing and reusing design is key in software development and XML is described as being interoperable with existing workflows such as IDEs as well as its programmatic potential to use the format in other integration capacities. 

 The author categorises existing design pattern languages into 4 groups: mathematical, UML-based, general programming language-based and those based on ontology and follow this with a literature review these areas.

 DPDL is outlined with its design objectives heavily dependent on the XML format i.e. its descriptive structure, extensibility and interoperability features and is widely used.

 The components that make up a design patterns are identified, and are represented within the specification as XML attributes such as identification attributes (including meta data to describe the context of the design pattern), structural attributes, which are a static view of classes, their operations and relationships between them and finally behavioural elements which portray the dynamic nature of communication sequences of processes and activities. 

 A DPDL validation exercise discusses an implementation of DPDL, used in a programmatical capacity, to generate from XML, a graphical representation of design patterns and sequence diagrams using C#. This is used later to validate a practical example of the language’s ability to facilitate graphically representing the Mediator Pattern, which is then defined and followed by an illustrative implementation of DPDL. 

 DPDL Limitations are discussed which include it being arguably more difficult to interpret textual description based on XML and the lack of any design-pattern validation.

It is also noted that currently the specification is limited to describing object-orientated design patterns and the potential to describe other domains such as workflow-based and authentication flows. 

 The authors note also that it can be difficult to identify design patterns in source code and only once this is done can it be represented as a design pattern in DPDL.

 The effects of interpreting design patterns to aid understanding discussed by Scanniello et al. (2015) and to express, represent and transmit them, discussed by Khwaja and Alshayeb (2013) leads to a need to qualify the impact that they have on code itself:

 Jaafar et al. (2016) discusses the effects of design pattern coupling and dependencies that are inherent in their design, particularly its impact on the propagation of change and faults in the source code.

The study defines design patterns as broadly good design and anti-patterns as conversely bad, with the latter having unfavourable tendencies to increase faults. The authors claim that design patterns which are inherently based on dependencies too could propagate change and faults. 

The study investigates the impact of various types of dependency-relationships that ordinary classes have with design patterns or anti-pattern structures. 

Two types of relationships are identified: static, where one object is composed or is an aggregation of another and co-changing relationships where one change necessitates another change in another related class. 

The study’s analysis is based on source code for three open-source products, all based on Java, namely ArgoUML, JFreeChart and XercesJ.  

The methodology discusses the technology used to identify patterns and relationships, namely DeMiMMA and DÉCOR for design pattern identification and the use of the Ptidej suite to understand the relationships between classes.  

Furthermore, the Mococha tool is used to identify the nature of any code changes that occur within the software forming these relationships and identifies which changes affect classes with these relationships in both design and anti-patterns. This is based on examining the code repositories and relating changes to the referenced bugs in a bug-tracking database. 

They identify 10 anti-patterns that will be used in the study, including AntiSingleton, SwissArmyKnife, ComplexClass and Blob and 6 design patterns: Prototype, Command, Factory Method, Composite, Observer and Decorator. 

The research questions are outlined, namely, to determine if participating classes who share static or co-change dependencies with both design and anti-patterns are more or less susceptible to faults i.e. bugs.  

The analysis of the fault occurrences and types of relationships between classes, shows that static relationships and co-change with anti-patterns have more faults. Static relationships with design patterns do not have significantly more faults - however (crucially) co-changing relationships with design patterns do.

 Threats to validity draws extensive acknowledgement of possible corrupting factors including difficulty to distinguish between overlapping dependencies. 

The related work details the technologies and work by others that influenced use in the study is presented, particularly those mentioned previously used to detect design and anti-patterns and the dependency relationships. Including the mechanism behind detecting faults in source code. 

The conclusion outlines the impact of the future, including the use the study’s outcome as a fault prediction model. 

Comparisons and evaluation of contribution to topic;

The contribution Scanniello et al. (2015) makes is in providing empirical evidence that various representations of design-pattern documentation have cognitive implications on improving source code comprehension. It has ramification for source-code maintenance, developer-onboarding etc.  The rigorous nature of their experiments, formulation of a ‘comprehension metric’ will help to serve as a point-of-reference for further studies into quantifying source-code comprehensibility. The impact of people’s experience on comprehension is also empirically investigated and its treatment is noteworthy - particularly the positive effect that existing education has on the ability to use documentation effectively. Also, a key implication is that correct identification of design patterns in source code is a crucial component of comprehension of design pattern in general but specifically in usage of associated design pattern documentation. 

Khwaja and Alshayeb (2013) contribute a practical, uniform framework for the description of any design pattern, that can crucially be then be transformed and/or integrated new ways. A good survey of existing design pattern languages provides a good understanding of the current design pattern language landscape. Identification of the structural components that make up a design pattern is useful as well as the corresponding use thereof to inform the design of DPDL itself. Also useful is the modelling of object-calling behaviour which has implications for use in characterising or documenting any arbitrary procedural piece of code which can itself greatly aid comprehension, documentation and design of existing systems. The potential to use DPDL to create/generate new diverse forms of design-pattern representations is compelling. 

Jaafar et al. (2016) contribute towards an understanding of what the nature of relationships having static and co-change dependencies have with design/anti-patterns and provide a useful empirical study to corroborate often widely assumed suggestions that design patterns cause less faults and that anti-patterns are susceptible to more. However, more importantly is the discovery that design patterns that are heavily modified with participating classes(co-change) offer the same risk of faults. A useful use and survey of technology to lexically detect patterns and relationships is well described and useful to future researchers in this area, particularly considering the difficulty previously noted of this endeavour. A fault prediction system based on the ideas of analysing static and co-changing dependencies is novel. 


An interesting observation around applicability of design pattern representations (specifically as documentation) is that generally these are mostly limited to textual or graphical forms, and that some people participants found that one format not as useful/appealing as another. Furthermore, Scanniello et al. (2015) shows that experience also affects representational preferences. 

This suggests that alternative or perhaps newer forms of representations for documentation that cater for these varying preferences including experiences are needed: a format perhaps that can be transformed into any representation and embedded into source code. This is one of the implications of a uniform pattern description language as proposed by Khwaja and Alshayeb (2013). 

It also seems important to recognise that integration of design pattern documentation directly in source code (other than textual varieties) or development environment (IDEs) is lacking, which otherwise could help keep code and design pattern documentation better aligned, integrated and maintainable.

Like Scanniello et al (2015), Khwaja and Alshayeb (2013) identify the same issue: correct recognition of design patterns in source code is difficult. Future research into identification should be sought and the technologies identified by Jaafar et al. (2016) could assist in that. 

Another interesting intersection is that because design pattern identification and usages of associated documentation heavily relies on developers already having knowledge about them, it highlights that formal education is crucial. Also, communication and learning through code maintenance activities such as bug fixing particularly in inexperienced team members might actually be counterintuitively impacted due to inability to identify them.

There seems to be a clear link between the proposed DPDL by Khwaja and Alshayeb (2013) with those based on ontological methods, but this link is not clearly made, or similarities thoroughly investigated. The potential however of DPDL to be used to generate textual descriptions directly in source code or IDE or even indirectly as resources or as part of ‘the build process’ to generate documentation is noteworthy. As too is the potential to generate classes/objects by utilizing templating technologies like T4 templating and Roslyn. (Harrison, 2016[6]

An interesting consideration presented in the study of design pattern dependencies is the negative impact that refactoring may have on design pattern-based codebases, as refactoring is mostly considered a positive endeavour that encourages co-change. 

Another useful observation is that some design patterns are inherently prone to changes such as the Observer pattern and some being overly complex such as the Composite pattern, and as such could be undesirable to implement (both are described independently in Freeman et al., (2003)[7] ). With respects to these patterns, and perhaps design patterns in general, is the risk that hidden complexity in their design due to their abstract in nature makes it difficult in cognitively visualizing side effects, promoting faults in using them and maintaining adjacent code.

These blemishes in an otherwise often perfectly perceived prescriptive advice, gives pause for consideration when considering the impact of implementing some design patterns in future projects and the importance for unit testing codebases. 

It is interesting to note that Khwaja and Alshayeb (2013) indicates that design patterns are used as a communication aid amongst developers however the empirical research by Scanniello et al. (2015) suggests otherwise.


References & Footnotes
  1. The Open university, 2020a: The Open University (2020a) ‘Unit 7: Design patterns: 3 Design patterns, ‘M813 Block 2: Software Development’, [Online] Available at (accessed 22 August 2020)
  2. Scanniello et al. (2015): Scanniello, G., Gravino, C., Risi, M., Tortora, G., Dodero, G., 2015. Documenting Design-Pattern Instances: A Family of Experiments on Source-Code Comprehensibility. ACM Transactions on Software Engineering and Methodology (TOSEM) 24, 1–35.
  3. Khwaja and Alshayeb (2013): Khwaja, S., Alshayeb, M., 2013. Towards design pattern definition language. Software: Practice and Experience 43, 747–757.
  4. Jaafar et al. (2016): Jaafar, F., Guéhéneuc, Y.-G., Hamel, S., Khomh, F., Zulkernine, M., 2016. Evaluating the impact of design pattern and anti-pattern dependencies on changes and faults. Empirical Software Engineering 21, 896–931.
  5. The Open university, 2020b: The Open University (2020b) ‘Unit 5: Design: P1: Strive for loosely coupled design between objects that interact’, ‘M813 Block 2: Software Development’, Available at (accessed 22 August 2020).
  6. Harrison, 2016: Harrison, Nick, (2016). ‘Roslyn - Generate JavaScript with Roslyn and T4 Templates [WWW Document]’. Available at (accessed 22 August 2020).
  7. Freeman et al., 2003: Freeman, E., Robson, E., Bates, B., Sierra, K. (2003) The Iterator and Composite Patterns: Head First Design Patterns [Online], O’Reilly Media, O’Reilly, Sebastopol. Available at (Accessed 22 August 2020)

Comments powered by CComment