A Learning Path (Article 8)
8 minute read
Is your naming process effective for working with others?
There are two hard problems that we face constantly.
- Naming
- Cache invalidation
- Off by 1 errors
With naming being such a nemesis, it would be valuable to have techniques to make it easier. Naming as a Process describes those techniques.
And (4 years later) I re-wrote my blog series and added a summary and learning path (this post) to adopt naming as a process. Why did it take me 4 years to write?
My significant blockers were:
- I needed to iterate and improve the steps;
- I realized how disciplined refactoring grounds the naming process and needing to figure out how to teach just enough of it; and
- I needed a series of on-the-job practice guides to really help people learn the process.
So, 4 years later I return to you with a very grounded and practiced way to adopt naming as a process.
Names Go Through 7 steps, but the Process is Really 3 Phases
One of the many nuances I learned in those four years is that the 7-step naming process actually breaks down in three major phases, the first one being the one you can learn now.
.clear { clear: both; } .side-icon figure { margin: 0 0 1em 0; }
The first phase is simply getting realizations about what the code does. Based on those insights, you would then record that information into a name. This includes the steps from Missing or Misleading through Nonsense, Honest, and Honest and Complete. The only refactorings you need are extract method and rename. The learning path provided in this post will guide you through it.
The second phase is using those names to guide correct chunking. Of the seven stages of naming, this contains the Do the Right Thing step. The only concept is to refactor the structure to match the name. However, which structural refactorings you need depends on your context. Deep Roots, my company built to eliminate technical waste through refactoring habit shifts, offers 60+ potential habits that developers might need to perform that step. However, knowing which of those steps to learn requires coaching guidance.
The third and final phase is using the chunks to guide the right design. Frankly, the combination of the first two phases represents all the new information and behavior shifts. However, this final phase uses your structural and naming refactorings for a new purpose. There is little to learn here, just lots of practice.
Let’s Learn Phase One!
The naming blog series gave you a sequential process, but that does not mean that’s the order to learn it. We wouldn’t teach our children how to cook by having them create a menu, go shopping, and then all the steps involved with cooking the meal. We would teach them some micro-steps within the cooking process to give them a context of the overall structure, such as how to measure ingredients or identify easy recipes. Once they master cooking a dish we would add on the up-front activities.
The following sequence ensures each micro-step is easy to learn and provides immediate value. This is not the same as the order a name goes through.
- Mob for awareness. Try out all the parts together, preferably with a skilled guide.
- Start with Step 2 of the naming process (yes, skip and ignore step 1 for now): making an honest name. This step is useful on its own, and you have plenty of bad names available to work with.
- Now add Step 1 of the naming process: using obvious nonsense. This splits one activity out of step 2, making the process easier.
- Finally go on to Step 3 of the naming process: being completely honest (eventually). This gives you an iterative way to build on step 2 and eventually get a good name.
- Phase 1 mindshift: put insights into names. This brings the techniques together and makes it easy to pick up from your colleague’s partial progress.
While you are welcome to try this out on your own, Deep Roots has also created a legacy code mastery workshop that includes Naming as a Process.
Mob for awareness
Get together as a mob with a long method. Your goal is to get the entire method to be Honest, and some to be well on the way towards Honest and Complete. Your second goal is to do this in as many commits as you can, where each is a legitimate improvement of some name. Timebox for an hour, and do a quick retrospective at the end.
The mob will give you awareness of the whole process. You will also work through several problems together that would otherwise stump you for an hour when alone. You won’t learn anything well enough to apply it on your own, but you will get a feel for the flow.
Tips:
- Set up a good mobbing environment.
- Keep the mob flowing. Don’t stop to discuss. Just try something. If it doesn’t work, revert.
- Be explicit about the goal. You are trying out a new way of working with names so don’t expect to make any progress on a story.
Shift 1: Get to Honest
After applying this shift you will know which names you can’t trust, so you will have some names that you can trust. This will speed up your story development.
Your goal is to develop a habit of noticing when a name is not trustworthy, and then making it trustworthy. Even if it is not very informative, it should explicitly state what it is informing you about and whether there are things it is not informing you about.
Shift 2: Get to Obvious Nonsense
This shift will speed up your ability to extract useful code chunks from long methods, resulting in much faster productivity on stories that touch long methods.
The target habit is to identify one separable chunk and pull it out without delaying to figure out what to call it. Simply dividing the work allows you to apply your whole brain to each part of the task.
You will also identify misleading names and immediately turn them into obvious nonsense without the delay to understand them. This will let you quickly fix a common code trap without getting sidetracked, reducing the number of bugs you write.
Shift 3: Get to Completely Honest by Adding Knowns
Applying this shift over time will decrease the time it takes for each story. You will need to read less code because each name will tell you everything you need to know.
The target habit is to iteratively build knowledge into names by adding one clause at a time (Section: Expand the Known). Because each step is better than before, you can check in and move on at any time. This allows you to discover names as you need them and avoids ratholing during refactoring.
Shift 4: Get to Completely Honest by Narrowing Unknowns
Applying this shift will allow you to quickly identify code that you won’t have to read any further.
This shift is within the same naming stage of getting to completely honest, but doing it by narrowing what you don’t know instead of adding what you do know (Shift 3).
The target habit is the same as Shift 3, where you iteratively build knowledge into names by adding one clause at a time (Section: Narrow the Unknown). However, this time you’re narrowing what you don’t know.
The Aha: Putting Insights into Names
This mindset makes the four shifts become sustainable. It will allow you to stop refactoring more quickly, while colleagues pick up from where you left off as needed.
- You quickly assess the current state of a name
- You take the minimum steps to get the name to meet your need for the current story
- You leave the name in an incomplete state that will be extended by the next person
- Your team’s adoption of this ability improves the names exactly as much as needed without anyone doing rework
Applying Phase One Every Day
Incremental naming to get to completely honest names is wonderful! However, it can be hard to sustain if that is all you learn. We need an equally incremental coding approach that works at the team level. Deep Roots calls that the Insight Loop.
The Insight Loop consists of three habits that support each other:
- Start Refactoring Safely
- Naming is a Process
- Know When to Stop
The Insight Loop gives a team a structured, consistent way to see and make one design improvement or functionality improvement at a time. Implementing this will allow a team to consistently apply Naming as a Process forever.
How Can We Do Phase Two?
Phase One is a set of practices that you can do — yes, it’s much more sustainable with our workshop, but you are able to implement Phase One both alone and without help.
Why can’t we keep going like this? Because Phase One is an approach that universally works across all code design flaws and work contexts. That’s not true for later phases.
The next phase for naming completely depends on the specific problems you have in your code. We simply don’t know which of the many habits are needed for your context, so can’t offer the self-directed option, let alone a blog series.
However, you can build a customized learning path for your team’s codebase using our broader habit catalog. Email us to learn more about our customization options.
What is this Phase Three Thing Then?
Quite simply, it’s the final phase that names go through. It doesn’t require any new skills; you just combine all the skills you learned in the first two phases to address a new problem.
Phase Three appears to include significant additional design skills. In truth, however, mastery of the disciplined refactorings and incremental design approach that you learned in the first two phases will make it easy for you to teach yourself design concepts as you need them. While this does not require any fundamentally new concept or consulting, there is no passing GO (skipping Phase Two) in order to get here!
Adopt Now
Help your team adopt Naming as a Process now!