A Learning Path (Article 8)

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.

7 stages of naming

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:

  1. I needed to iterate and improve the steps; 
  2. I realized how disciplined refactoring grounds the naming process and needing to figure out how to teach just enough of it; and
  3. 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.

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. This 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 the consulting aspect I offer.

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.

  1. Mob for awareness. Try out all the parts together, preferably with a skilled guide.
  2. 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.
  3. Now add Step 1 of the naming process: using obvious nonsense. This splits one activity out of step 2, making the process easier.
  4. 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.
  5. 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 two options to make learning faster and easier. Our self-adoption package provides support content for you to guide your team’s adoption. Our coached adoption package extends the support content with my (Arlo’s) direct guidance.

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:

  • Keep the mob flowing. Don’t stop to discuss. Just try something. If it doesn’t work, revert.
  • Set up a good mobbing environment.
  • Be explicit about the goal: you are trying out a new way of working with names, and don’t expect it will make any progress on a story.

Our self-adoption package includes

  • A screencast video where a master takes a method from messy to clean using these steps.
  • Mob preparation guide.
  • Questions and challenges to pepper into your mob session.

Our coached adoption package adds

  • Arlo facilitates your mob.
  • Additional topics & advice as they come up.

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.

Our self-adoption package includes

  • A how-to video, a visual reminder, a how-to guide, and a checklist to practice on the job.
  • A video resolving the naming convention objections.

Our coached adoption package adds

  • Discussion with mentor around all above content, particularly applying the technique on the job.
  • Retrospective with mentor to ensure everyone got it.
  • Mentoring on what to measure to make the ROI visible to you and your boss.

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.

Another form has come to light since writing the article. 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.

Our self-adoption package includes

  • A how-to video, a visual reminder, a how-to guide, and a checklist to practice on the job.
  • A video on seeing the value of obvious nonsense.

Our coached adoption package adds

  • Discussion with mentor around all above content, particularly applying the technique on the job.
  • Retrospective with mentor to ensure everyone got it.

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.

Our self-adoption package includes

  • A how-to video, a visual reminder, a how-to guide, and a checklist to practice on the job.
  • A video on resolving worries that it will never get to complete.

Our coached adoption package adds

  • Discussion with mentor around all above content, particularly applying the technique on the job.
  • Retrospective with mentor to ensure everyone got it.

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.

Our self-adoption package includes

  • A how-to video, a visual reminder, a how-to guide, and a checklist to practice on the job.
  • A video on seeing the value of including unknowns in names.

Our coached adoption package adds

  • Discussion with mentor around all above content, particularly applying the technique on the job.
  • Retrospective with mentor to ensure everyone got it.

The AHA: Putting Insights into Names

This shift makes the gains from the first 3 shifts become sustainable. It will allow you to stop refactoring more quickly, while colleagues pick up from where you left off as needed.

The focus for this shift is to deepen your awareness of the mindset behind the first three shifts. The more you become fluent at taking a name forward one step at a time (practice), the more that mindset becomes a part of your core coding value.

  • 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

How Can We Do Phase Two?

Phase One is a set of practices that you can do – yes, it’s better with more resources from the self-directed package and much more sustainably changing for the team with the coached package; however, 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 languages, code design flaws, developer levels, and work contexts. 

Deep Roots only offers two self-directed packages, both of which have universal application. This particular phase is a subset of a bigger self-directed package that introduces developers to disciplined refactoring via the Insight Loop, but the other two habits don’t directly impact the naming process. 

That being said, the actual 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 habit catalog, which will be embedded here by Thanksgiving 2019 (end of November). Come back here to check it out or follow us at @digdeeproots for the release announcement!

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!

Self-Directed and Coached Support Packages

Self-Directed
Habit Change
Coached
Habit Change
Who ChangesMost of teamWhole team
ResultsMost active code becomes trustworthy and you can tell when names are misleadingAll active code becomes trustworthy
SuccessReliableGuaranteed
ContainsGuides, videos, and checklistsGuides, videos, and checklists
and
Arlo coaching you
Time before Results2 months8 days
$2,000
Contact us
$1,000 / day
Clear Actions
X
X
Visual Aids
X
X
Slack Channel
X
X
Video Support
X
X
Address Resistance
X
(video)
X
(discussion)
Live Demo
X
Guided
Retrospectives
X

Self-Directed Package Contents

  • Visual Aid: multi-step process
  • Guide: Precise behavior shifts
  • Daily Checklist:
    • Shift 1: Make many honest names
    • Shift 2: From bad to less bad
    • Shift 3: Iterating towards more knowns
    • Shift 4: Iterating towards fewer unknowns
  • Helpful Videos:
    • Shifts 1-3: What to look for and what to do
    • Shift 1: Resolving the naming convention objections
    • Shift 2: Seeing the value of obvious nonsense
    • Shift 3: Resolving worries that it will never get to complete
    • Shift 4: Seeing the value of including unknowns in names

Coached Package Contents

Everything in self-directed package plus

  • Facilitated mobbing environment to see how it all works together
  • Coaching to turn each checklist into a sustained habit
  • Coaching metric tracking to demonstrate ROI
  • Remote in-person demonstration of what to look for and what to do
  • Discussions on video topics
  • Synchronous retrospective

Contact us

Deep Roots is

Deep Roots is on a mission to help you prevent software bugs. They have identified the hazards that make bugs happen. Their Code by Refactoring process shows you what behaviors create those hazards, and what specific shifts will help you change those hazardous conditions while continuing to deliver software at your current speed.

Neep help addressing this topic in your organization?

Reach out and we’ll get in touch to discuss more.