- Dynamic Curation
- Highlighting the Core
- Highlighting Inspiring Exemplars
- Guided Tours and Sightseeing Maps
- Summing Up: The Curator Preparing an Art Exhibition
- Summary
This chapter is from the book
This chapter is from the book
This chapter is from the book
Highlighting Inspiring Exemplars
The best documentation on how to write code is often the code that is already there. When I’m coaching teams on TDD, I pair-program randomly with developers on code bases I have never seen before. The developers pairing with me often behave as if they have never seen the code base before; for a new task, they might go looking for an example of something similar already there, and then they copy and paste it into a new case. A programmer might determine, for example, to find a service written by Fred, who is the team lead and is well respected by the rest of the team. However, Fred might not be great in every aspect of his code, and the flaws in his code may end up being replicated across the whole code base. In such situations, a good way to improve the code quality is to improve the examples of code that people imitate. Exemplary code should serve as a desirable model to imitate—or at least to inspire other developers. Sam Newman writes about this in his book Building Microservices:
You can point your colleagues to the exemplars during conversations and during pair-programming or mob-programming: “Let’s look at the class ShoppingCartResource, which is the most well-designed class and is exactly in the style of code we favor as a team.”
Conversations are perfect for sharing examplars, but some additional documentation can have benefits, too, when you are not present to point people in the right direction or when people are working on their own. You can use documentation to provide the equivalent of a big loud sign to signal a good examples (see Figure 5.3).
){kind=link}
Figure 5.3 Good example of code here!
Therefore: Highlight directly in the actual production code the places that are particularly good exemplars of a style or of a best practice you would like to encourage. Point your colleagues to these exemplars and advertise how to find them on their own. Take care of the exemplars so that they remain exemplary, for everyone to imitate in a way that will improve the overall code base.
Annotations are, of course, a perfect fit here: You can create a custom annotation to put on the few classes or methods that are the most exemplary. Of course, exemplars are useful only if their numbers are limited to those that are very best.
Decisions on what code is exemplary or not are best made collectively by the team. Make it a team exercise to find a consensus on the few exemplars to highlight with a special annotation.
Exemplars should be actual code used in production, not tutorial code, as Sam Newman says in Building Microservices:
In practice, an exemplar is hardly perfect in all aspects. It might be a very good example of design, but the code style might be a bit weak—or the other way round. My preferred solution would be to fix the weak aspect first. However, if that’s not possible or desirable, you should at least clarify why the exemplar is good and what aspect of it should not be considered exemplary. Here are a few examples of exemplars:
On a class: @Exemplar("A very good example of a REST resource with content negotiation and the use of URI-templates")
On a JavaScript file: @Exemplar("The best example of integrating Angular and Web Components")
On a package or a key class of this part of design: @Exemplar("A nicely designed example of CQRS")
On a particular class: @Exemplar(pros = "Excellent naming of the code", cons = "too much mutable state, we recommend immutable state")
Basically, marking exemplars directly in the code enables you to then ask your IDE something like “What code is a good example of writing a REST resource?” In an integrated documentation fashion, finding exemplars is only a matter of searching for all references of the @Exemplar annotation in your IDE. You can then just scroll the short list of results to decide which code will be the inspiration for your task.
Of course, there are caveats in the approach suggested before:
Software development is not supposed to be as much copying and pasting as thinking and solving problems. Highlighting exemplars does not give you license to copy and paste code.
Copying/pasting requires refactoring. As similar code accumulates, it must be refactored.
Marking the exemplars in the code is not meant to replace asking colleagues for exemplary code. Asking questions is good because it leads to conversations, and conversations are key for improving the code and the skills. Don’t reply “RTFM” (“read the flipping manual”) when asked for exemplars. Instead, go through the suggested exemplars in the IDE together to determine which one would be best for the task. Always take conversations as opportunities to improve something mutually.