Its Purpose?
Explicitly identifying code patterns in the code base as well as how and why they’re used helps new team members learn more about the system faster. Explaining the system in terms of well known patterns helps new team members identify variants and where patterns are being abused/mis-applied.
How Did We Execute It?
In trying to hand over some work to the support group, the team assembled a list of all patterns used in the system. We listed the pattern name, a reference to the pattern (either book or web link) and how it was being used in the system. We also wrote down the benefits or concerns each was bringing to the codebase. We listed each of these on the team wiki on a page called “System Patterns”.
When new people joined, I would print a copy of the wiki page, and then during or after walking through the System Architecture, helped them understand where they might use them or see them being used.
Image taken from Hubmedia’s photostream flickr stream under the Creative Commons Licence.
Why Is It Important?
Patterns are excellent vehicles for communicating intent and solutions to common problems. Identifying and explaining the system as a set of patterns helps new team members understand the system in much larger chunks, making it easier for new people to focus on absorbing incidental information. It also allows them to focus less on how the code works together, and more importantly focus on what the code does and what value it brings.
Well known pattern names help to identify common problems in the domain, and what the team’s general approach is for solving them.
The number of patterns also indicate a qualitative attribute of your system. If you have a very large system, and only a small number of patterns it potentially indicates that everything is done in very different ways and needs some refactoring. Alternatively if these small number of patterns are used everywhere in the system, then it could already be a very well refactored system. I would also consider looking at a very large set of patterns for a small code base as that might indicate over-design and excessive complexity. In both cases, I would watch out for patterns with only a handful of uses to see if they are actually useful or not.
Things To Watch Out For
Some new team members may not understand all the patterns used in the system. Giving them reading references helps though you may need to do more work to help them understand the pattern.
What I Might Try Next Time
I would revisit this list of patterns with new team members after they’d been in the code base for a while. I think although it’s useful to introduce the catalogue early, it would help to reinforce some of the larger picture after they’ve had an opportunity to discover more detail on their own.
Next time I would also try to link to some part of the codebase that implements the “ideal” version of the pattern and the benefits the team reaps.
