Deep Roots – Naming as a Process

Articles: Naming as a Process (Article 1)

Thu, 17 Oct 2019 00:00:00 +0000

We all know naming is a pain in the ass and you can’t trust the names in your code. But it doesn’t have to be that way.

Many people try to come up with a great name all at once. This is hard and rarely works well. The problem is that naming is design. Here are the things you are typically trying to do all at once while naming:

Deciding the things the code should do
Deciding which things go together
Deciding which abstractions best represent those clusters
Picking a name that clarifies intent
Picking a name that distinguishes from all the other similar intents
Describing the side effects of the code
Keeping your name under 15 characters

This is why naming is hard.

Our brains can’t juggle seven cognitively complicated tasks at once. After brain overload, most of us give up and settle for a crappy name.

Naming something perfectly the first time isn’t going to happen. Let’s talk about evolutionary naming.

The easiest approach for finding good names is to progress along a series of regular steps.

The solution … annoyingly simplified

At each step, I look at one part of the code, understand one kind of thing that is happening, have an insight, and write it down. I repeat this until I have moved one step down this list. I keep going until I have a good enough name for my purpose.

The big picture

Those of you who are reading ahead will wonder why I am focusing on names. I mean, names are annoying to come up with and perhaps this will make it easier, but is that really a problem?

The answer to that question lies at the heart of understanding, preventing, and paying off technical waste.

The source of all technical waste

Wasteful code is any code that is hard to scan. Technical waste is anything that increases the difficulty of reading code.

Me.

My focus on code reading may seem odd to many of you. After all, we’re programmers. We’re good at reading complex code, and our job is to update code. Shouldn’t the definition of technical waste be something about the cost and risk of changing code?

This is.

It turns out that the largest single thing developers spend time doing is reading code.

More than design.
More than writing code.
More than scanning.
And yes. Even more than meetings (well, probably).

According to an analysis from Eclipse data, programmers spend around 60-70% of their entire programming time reading code.

So if we want to be more efficient, we need to improve our ability to read code.

It’s about risk too

Bugs aren’t random. Unsurprisingly, bugs get written more often when:

methods are long or deeply nested (cyclomatic complexity),
concepts are spread around,
code does multiple things,
there are side effects.

Make a method longer or make code more complex to reason about and people write more bugs when they edit it.

But those aren’t the #1 cause of bugs. Poor naming was #2 but became #1 when inconsistent indentation was solved by IDE’s.

Bugs come from incomplete understanding

Now that we know bugs aren’t random, let’s look at what leads to a bug.

Mistakes happen when our mental model doesn’t match the reality of the code.
Neuroscience shows that our short-term memory only has seven registers.

So if the real code would take more than seven registers to model, we can’t help but write bugs. So let’s make the code take fewer registers. Since it takes more registers to comprehend code than to remember what it does, the easiest way to reduce registers is to make the code easy to comprehend.

So if our definition of technical debt is code that is difficult, expensive, or risky to change, then the root cause of that is code that is hard to scan. And what makes code easy to scan? Good names.

Which brings us back to names

Definitions are where we communicate instructions to the computer. Names are the place we communicate our insights and intentions to other humans.

Implementing the solution

Remember, the annoyingly simplified solution is to have one insight at a time, write it into a name, and repeat until your name shifts to the next stage. The remaining challenge is to learn how to make each kind of naming shift. For each stage you will need to know:

where to look for insights,
what kinds of insights to glean,
how to write them down in a name,
how to use tools to do this at speed, and
how to know when you are done.

We have extracted this into a series of micro-skills that are designed to be easy to learn and pay off with advantages from the start. That sequence is Code by Refactoring. Start by helping your team learn Naming as a Process.

Adopt Now

Help your team adopt Naming as a Process now!

See How it Works

Next up: Get to Obvious Nonsense.

Or read the whole Naming as a Process blog series.

Articles: Get to Obvious Nonsense (Article 2)

Wed, 16 Oct 2019 00:00:00 +0000

The two most terrible kinds of names are also the most common:

Names that mislead you, and
Important parts of something else, so they don’t even have a name.

In the spirit of naming as a process, we want a quick way to fix these two problems. It needs to be trivially fast and light, so that we can do it the hundreds of thousands of times that most codebases need.

We will turn Missing and Misleading into Obvious Nonsense.

Obvious Nonsense isn’t great, but at least it isn’t misleading! Now it becomes obvious to everybody on the team that the name is nonsense and they won’t be tricked into writing a bug.

Fixing Missing Names

Why start there? Making code readable is our ultimate goal, however often code has many different concepts in the same method/class/field/variable. We want to pull out each concept and give it a name. When a concept is embedded within another thing, we can see its name as missing.

Part 1: Look at Long Things

Focus on long things that are related to the task at hand; the long methods, long classes, long files, long argument lists, long expressions. All of these are more readable and consumable when broken into pieces with one concept each.

Part 2: Look for 1 lump that hangs together

I look around for things that seem to go together. Examples include:

A paragraph of statements
A non-obvious expression (usually involving arithmetic or logic)
A set of parameters that are frequently passed together.
A set of parameters that are used together in the method (such as a bool which indicates whether another variable is valid)

I just pick one chunk that hangs together. It doesn’t really matter how good a chunk I find. There are techniques that will find better chunks and speed up my understanding, but any chunk will get me one step closer. We can leave refinement for later. Good is too expensive; all I want is better (quickly).

Part 3: Write down by extracting it as Applesauce

We want to understand this lump of stuff. The first step is to create a thing to be named. Typical languages allow us to name any of 5 different things, so we must create one of these things. To do this, we use one of 5 refactorings:

Extract Method (to name a bunch of statements)
Introduce Variable, Parameter, or Field (to name an expression)
Introduce Parameter Object (to name a set of parameters that are passed around together)

We want an Obvious Nonsense name, so use Applesauce. Everyone on the team will instantly recognize it as nonsense. Also, because there is only one nonsense name, you will need to make this name honest (the next step) before you make more nonsense in the same scope.

`Applesauce`? Really?!

Obvious nonsense feels unprofessional. It’s not how you want to represent your work. Creating bugs, however, is more unprofessional - we are just more used to it and have come to accept it. Things that contain many unnamed concepts are difficult to reason about, which will cause developers to write bugs.

The self-directed and coached habit changes for this process address common resistances, including the urge to take the time to create a good name.

Finding Better Chunks in Long Methods

There are a few ways for you to hone your chunk finding skills. Once you’re in a long method and you see that there are possible missing names, use these strategies to find the best pieces to break out.

Look at the Bottom First

Long methods tend to be organized as:

guard clauses
use parameters to read the data the method actually wants into local variables
process
calculate a result
either write it down somewhere or return it.

This means that the more important stuff is near the end of the method. So start looking for chunks from the bottom, not the top.

This also makes extraction easier in most languages, because functions often allow multiple parameters but only one return value. So it is easier to flow messy information (like a bunch of local variables) into a function than out. This is not a problem in languages with functions that have the same cardinality for both parameter lists and returns (support destructuring return like Python or support only one parameter like Haskell).

Use Binary Search to Read Less

In general you’re not reading code for the joy of reading it. You’re trying to accomplish something. Use that something to guide what code you bother reading.

Use binary search to quickly find chunks that are highly relevant. Look for large chunks that don’t contain whatever it is you are seeking, or small chunks that do. Either quickly reduces the search space.

Foreshadowing a bit into the next step, when you extract a large chunk of code you know to not be related, just get the name up to barely Honest and then move on. For example, you could call it probably_DoStuffUnrelatedTo[whatever]()].

Follow Control Structures

Long methods are often dominated by a single control structure (after the guard clauses and fetching data into locals). The body of that control structure is often a good target. If there are multiple control structures in sequence, instead take the whole last control structure.

For example, if a method BecomeFroglike() contains one giant foreach loop, extract the body of the loop and call it MakeOne[whatever the control variable is]BecomeFroglike().

And if a method contains a foreach loop, then an if block, then another foreach loop, extract those into three methods, each taking the whole control structure. The outer method is then just a series of 3 method calls in sequence.

Exception handling is a little special. The body of a try block is often a good target for extraction. I usually name the resulting function *_Impl(). Complicated catch blocks are usually not worth extracting (though there are exceptions), so instead look for ways to extract the useful bits away from them.

Fixing Misleading Names

Another common challenge to reading code is when the name is indicates something different than what it does. When a concept is not being represented accurately by the name, we say its name is misleading.

Part 1: Look at Names that you are using

Focus on whatever names you encounter in the code you are reading.

Part 2: Look for under-information or misinformation

I look around for partial lies. Examples include:

A method named by when it is called in a lifecycle (PageLoad, PreInit).
A variable named the same as its type (GridSquare gridsquare).
Method name that leaves out critical information (method named composeName that also writes that name to the database).
Any name that ends in -er or -Utils (DocumentManager, CalculationUtils).

Part 3: Write down by renaming it to `Applesauce`

Don’t bother trying to figure out what it does or a good name for it. Just call it Applesauce and move on with your coding. We have the social norm that should always be good; however, if the name is misleading, even if it looks good, is not good. Misleading names will cause someone to write bugs.

Check it in!

I used to consider whether to check in at this point. It feels so small, and Applesauce feels like such a terrible name!

After 4 more years of practicing this, however, I no longer consider. I always check in.

Both of these changes make the code better. Not a lot better, but better. They are fast, easy, safe, and don’t make anything worse. By checking them in I immediately get back to a clean slate and am ready for whatever comes next.

Replacing a missing name tends to result in more insights about the code, so it is likely that both this commit and the next will be large. I want to split this up from that. Replacing a misleading name will almost always prevent one future bug. It is worth checking that in immediately so that there is no chance a failure at my next task will roll this back. Either way, check in now.

Adopt Now

Help your team adopt Naming as a Process now!

See How it Works

Next up: make our fresh Obvious Nonsense name become Honest.

Or read the whole Naming as a Process blog series.

Articles: Get to Honest (Article 3)

Tue, 15 Oct 2019 00:00:00 +0000

We have a thing with a name. But its name is obvious nonsense.

One of my more gnarly experiences was when I worked within a system that spoke to the FAA’s system. This particular method was named PreLoad(), telling me when the system calls the method (not very useful). The problem is that there is a missing name. Nothing tells me what would happen on PreLoad().

Based on Article 2, I then extracted the entire body of PreLoad() and called it Applesauce(). At that point, the code explicitly says that upon PreLoad(), do Applesauce().

Now we want to make Applesauce() honest.

Making the Name Honest

I want to make the name honest. It doesn’t need to be completely honest. It just needs to tell me one honest thing. I look at the method to figure out one thing that appears to be key to its execution. I just read through the body and see what appears central.

Part 1: Look inside the body

Focus on inside the body. Look for patterns that repeat here or between this and other methods.

I find it useful to look for variables that are system components (“database,” “screen,” “network,” “service”), look where the return value comes from, and see if something is used many times.

Part 2: Look for one thing the code does

As you look for simply one thing that the code inside the body does, consider also the judgment of how easy it will be to work with, how safe it is, or other useful traits.

In the example, I noticed that there was a global named db that was used a lot. Several places created recordset objects, set values, and read or wrote them using the db. Since it mixed reads and writes, I named the method probably_doSomethingEvilToTheDatabase_AndStuff().

As a name, doSomethingEvilToTheDatabase() is “interesting” enough. Why would I also write probably_ and _AndStuff? I wasn’t certain what the method does, but I had found one thing, and frankly, wasn’t 100% on that one. The probably_ informed my team that I wasn’t certain that it does the one thing I was saying it does. The _AndStuff informed my team that this name needs more iteration. It’s honest, but not complete.

Meanwhile, it is honest in several ways, recording several insights that I had.

The main effect of the method seems to involve the database.
I don’t yet understand what it is doing to the database.
I am getting all judgy about how it is treating the poor database. I don’t like it.
It does more things that I don’t understand at all.

The last three insights are as important as the first. Even if I wandered away at this point, a future reader of the code would have some insight. They wouldn’t know what the method did, but they’d be properly wary of it.

They’d know that no one knows exactly what it does, it does that thing to the central database, and the last person to touch it thought it was doing some nasty stuff. Good! I’ve transmitted all the knowledge that I have about this method. I’ve put them in the proper frame of mind for working with it.

Part 3: Write down by renaming to a better name

The components necessary for this better name includes two things:

One honest thing it does; and
Clarity about what we don’t know yet.

The way you perform the renaming is important. Don’t just edit the name; use a rename refactoring. When we edit the name we have a chance of accidentally changing behavior in some way, but when you use a rename refactoring, you ensure safety.

Be specific!

The most common way to screw up at this point is to be too general in your name. Being specific is good!

The intent of naming in this way is to allow a reader to understand a chunk of code without looking at it, just by looking at the name for that chunk of code. That reader needs specific detailed knowledge. So the name has to be specific.

For example, I could have named my function handleFlightInfoSomehow(). That would have been honest, but it hides the potential risky thing done to a very important part of the system. Thus doSomethingEvilToTheDatabase is more specific as to the risk.

Looking ahead just a bit, the next step will be to make the name convey everything the code is doing (be Honest and Complete). If we are specific, then the only route to completeness is to add to the name. I keep the same precision but add more description.

If I am overly general or imprecise now, then it most or all of the things the function does will be already roughly describable by the name. This will make it a lot harder for me to see the things that aren’t yet conveyed in the name, which will make it harder to create a name that fully describes the code behind it.

Not just for functions or nonsense names

This step applies when naming classes or variables as well as bad names that are not yet obvious nonsense. Common bad names for classes are anything that ends in -Manager or -Operations. Poorly named variables are usually named the same thing as their type.

In either case, we need to have one insight into this thing. What is one important responsibility of the class? For a variable, what differentiates this one Foo instance from all the other Foo instances that might be out there? How does the code using the variable think of this one? Whatever that insight is, write it down.

Adopt Now

Help your team adopt Naming as a Process now!

See How it Works

Next up: make how our basically honest names become completely honest.

Or read the whole Naming as a Process blog series.

Articles: Get to Completely Honest (Article 4)

Mon, 14 Oct 2019 00:00:00 +0000

I need to make my name fully describe everything this method does. Each level of improved naming should record more insights and make it easier for the next person to read the code.

This level actually makes it unnecessary for the next person to read the code. We want them to be able to trust that the name includes absolutely everything the method does so they can read and understand calling methods without having to read the method we’re fixing.

In the previous articles of this blog series, everything being done was accomplished in one step. However, being completely honest is hard so we need to take it in steps.

Each time you iterate on an honest name by making it more honest, you’ve made it easier on the next coder. A name might progress through this phase over the course of weeks or months. Eventually, though, the name will have become completely honest.

To complete “one more iteration” of the name becoming more honest, we look through the body of the method and find one of two things:

Expand the Known: find one more thing that it does. Add it to the name.
Narrow the Unknown: find one specific thing that we don’t know. Add it to the _AndStuff part of the name.

Expand the Known

The first option in your iteration of making the name more honest is simply finding one more thing that it does, which is explained in these three parts.

Part 1: Look inside the body

You know this by now. It is often useful to look for paragraphs or control structures.

Part 2: Look for one thing the code does that isn’t in the name

The process is:

Find one thing that the code does (an effect, a calculation, a result, a state change).
See if that is already included in the name (it might be a legitimate substep of something that is already in there).
If not, add it (see Part 3).

Don’t broaden the parts of the name. Your goal is not to find one abstraction that includes everything the method does. Your goal is to be precise; a reader should be able to read the method name and know exactly what the method does.

Part 3: Write down by adding a clause to the name

Ignore everything you’ve been taught about naming conventions. Long names are good. Conjunctions are good. Belaboring the point is good. Your only goal is to make sure that everything this thing does is represented in the name. And therefore anyone can trust the name. They no longer have to read the thing, just its name.

Imagine emailing the method name to someone. Just the name. Would they be able to generate exactly all of the things in the method body? They shouldn’t want to add any more things and they shouldn’t miss any.

The purpose of the second section (middle) of the name is to simply record what is known. Recall from previous articles that probably_ flags the team that there is uncertainty. _AndStuff records what is not known, while the center lists everything that is known. So add your new clause to the middle section.

Narrow the Unknown

The second option in your iteration of making the name more honest is finding one specific thing that we don’t know, which is explained in these three parts.

Part 1: Look inside the body or at the name

If you’re looking inside the body, focus on data or parameters you haven’t analyzed yet. This will help you add a clause to the set of unknowns.

Another strategy to consider is to:

Look at the name of the method,
Pick one of the clauses of unknowns that you want to narrow, and
Look at the parts of the method body that are related to that clause.

Part 2: Look for one category of things that the code doesn’t do

As the title suggests, you are looking for a category of things that the code doesn’t do, but also look for one partial truth for something the code does do. Let’s look at some examples.

Something that it doesn’t doAssume that I have a name _AndDoSomethingWithGraphicsContextAndStuff(). I realize that the method doesn’t write to the GC or use it to draw anything; it is read-only. I might name it to _AndDoSomethingReadOnlyToGraphicsContextAndStuff(). I don’t know what it does, but I’ve reduced the unknown.

A partial truth about what it does do
Assume my name includes _AndDoSomethingToDatabaseAndStuff(). I discover the code opens a write cursor and no reads, and rename to _AndWriteSomethingToDatabaseAndStuff(). I don’t yet know what is written, but I’ve exposed a partial truth and reduced the unknown.

The process is:

Identify one piece of data related to what you’re looking for (that may be a variable, parameter, or field).
Trace that data’s usage through the method to find one thing that is either done or not done with it.
Update the name accordingly (see Part 3).

Part 3: Write down by adding a clause to the name

The purpose of the _AndStuff section of the name is to record and quantify the unknown behaviors of this method. That is why we start simply with _AndStuff. However, now that you are moving from an Honest Name to Completely Honest, we can provide more precision than _AndStuff. So now you are going to record the more precise information you have by adding a clause to _AndStuff.

Finishing the iteration towards Completely Honest

A Completely Honest name will include only the middle section.

To get rid of the third section, we have to eliminate the last unknowns. We will need the object to be so readable that we know for a fact it doesn’t do anything beyond what we’ve said. It is usually easiest to identify all the impacted data and generate specific clauses in the third section. Once we’ve traced all the data, we know there can be no other impacts, so we can remove the general AndStuff(). Then we simply have to chase down every unknown clause one at a time until the third section is gone.

To get rid of the first section we have to be totally confident in the rest of the name. The probably_ indicates that we are not yet sure. To become totally confident we will need two things. First, we will need tests that verify the method does everything we say it does in the middle section. Second, we will need the object to be so readable that we know for a fact all unknowns are scoped by the third section. Once both are true, we can eliminate the probably_. However, later editors then need to either be justifiably confident in their naming steps or re-add the probably_. For this reason, removing the probably_ is often the last step.

Really big methods

Sometimes understanding a subcomponent requires extracting it and getting it to have a better name. This is especially common with long methods. When you do this, keep your focus on the main name. Extract a chunk and record insights only until you know whether or not it is important for naming your main thing. Then update the main name and move on.

Guard clauses are a good example. They’re usually easy to identify but take up a bunch of space. I won’t actually use them in the name of the thing (most of the time), but they can make it hard to read the rest.

I’ll extract a bunch of what I think are guard clauses, get the name for the extracted component to be Honest, and see if they actually are all guard clauses. If so then I leave them alone and come back to the main method.

I’ll extract guard clauses until I’m left with the residual. Then I’ll analyze that more deeply and make sure I get everything into the name of my main method. I might inline the guard clauses again when I am done, or just leave them named something like _ValidateAllInputs().

In the example from the FAA issue I shared in Article 3, I needed to take several steps to find all the things my method was doing. I eventually identified 4 main chunks of functionality, each of which happened in many steps. So my method became parseXmlAndStoreFlightToDatabaseAndLocalCacheAndAddToScreenIfVisible().

Things that aren’t methods

This step also applies to variable and class names.

Classes should be named by all of their individual responsibilities.
Variable names should include all the ways the variable is used.

In deep legacy code variables may be used in a surprising number of ways. An example is once when I had a poor, overused in/out parameter that I had to name searchHintThenBestMatchSoFarUntilItBecomesReturnValueOrReasonNoMatchWasFound.

There is a strong design rule that says classes should have a single responsibility. That’s true. However, in this step we are ignoring what “should” be true and trying to simply be completely honest about what is true right now. Classes often have a primary responsibility while also including a couple of other responsibilities that mostly make sense and are too small to break out. That being said, this naming stage is simply being completely honest about all of those responsibilities. We will decide what to do about the multiple responsibilities in the next step.

Naming by what it does, not by what it is

Here the insights that I’m having are all the important characteristics of the thing I am naming. I’m naming it by what it does, not by what it is. This shift is a critical step in eliminating god classes and long methods.

**Named by what it is…**When a thing is named by what it is, then it accumulates everything vaguely related to that identity. Use this when you want other coders to naturally gather related pieces of functionality from other code and increase cohesion.

**Named by what it does…**When it is named by every single thing it does, then our desire for shorter names drives us to have it do less stuff. Use this when you want other coders to break it apart and simplify each chunk.

How something is named will drive the behavior of how people will engage with it and the future evolution of the method, variable, or class.

Me.

Adopt Now

Help your team adopt Naming as a Process now!

See How it Works

Next up: use your completely honest name to guide the code to do what it should do.

Or read the whole Naming as a Process blog series.

Articles: Get to Does the Right Thing (Article 5)

Sun, 13 Oct 2019 00:00:00 +0000

Congratulations on having a completely honest name! It is a huge step to simply represent exactly what the code does. All of the steps until now collected information into the name. In making the name complete, we have now made it possible to reason over the responsibilities of the class/method/variable without having to read its full implementation. This sets us up to change its responsibilities, so now we’re going to use the name to guide chunking the code.

Part 1: Look only at the name

At this step, I look only at the name. I ignore both its usage sites and its body. The only question to ask is “does this name make sense?”

Part 2: Look for one responsibility to separate

The easiest way to find a responsibility to separate is to look for a name clause we want to eliminate. There are typically two kinds of clauses we want to eliminate. Each is found by one key question:

Is this clause unrelated to other clauses in the name?
Is this clause a concern we want to encapsulate?

Part 3: Write down by structurally refactoring

Writing it down requires structural refactoring by extracting or encapsulating one behavior of the thing. We need to keep the name completely honest. If we don’t like the name then we have to change what the thing does so that we can use a different name.

Can we get more specific than “structural refactoring???”

There are hundreds of different code patterns and destination patterns that each call for a different refactoring. Code by Refactoring is my attempt to gather those context-specific practices into an overall technique that implements Naming as a Process described in this blog series as well as several other key legacy coding ideas. While handling every possible structural change requires all of Code by Refactoring, the patterns common in your specific codebase require only some of the shifts.

Two especially common goals are 1) safely moving a responsibility from a method and 2) encapsulation. Code by Refactoring resolves these two goals in the Fix Complex Methods Changes Series. This particular series of habits help you refactor a complex method into a new system with identical behavior, but in a tidy readable way.

Once the habits have been learned within Fix Complex Methods, a developer might respond to a particular instance with an approach like these.

Safely moving a responsibility from a method

The most common cause is that my method does too many things. I want to split the responsibilities and update all the callers to use them separately. The challenge is flowing the data between the methods without creating a mess elsewhere.

An example is the handling of the XML and the database in parseXmlAndStoreFlightToDatabaseAndLocalCacheAndShowOnScreenIfVisible(). I’d like to split that into 2 parts: one that turns XML into a flight, and one that operates on a flight.

The solution is to find a series of refactorings that split methods and cluster their data as we go. This might entail moving methods between classes, transforming methods to take data via parameters instead of using fields, or introducing new classes. Fortunately, the impacts tend to be localized to just the method we are working on and all of its direct callers, which is easily handled as long as we have a good technique for Inline Method.

Here is a common case, used when we start with a simple static method.

Extract method all the stuff after the part ‘../../post/get-to-does-the-right-thing’I want to break out.
Introduce a parameter object for everything going into the new method.
Extract method the part ‘../../post/get-to-does-the-right-thing’I want to break out. Have it return the new parameter object.
Introduce a parameter object for this new method.
Extract method all the stuff before the part ‘../../post/get-to-does-the-right-thing’I want to break out. Have it return the new parameter object.
Split the name of the outer method up into names for the 3 parts based on what does what chunks.
Add any missing clauses required to make the names complete. For example, the above split may divide a calculation from the part ‘../../post/get-to-does-the-right-thing’that writes it somewhere. The outer method may just be named ...AndRecordYield...(). So I now have one inner part ‘../../post/get-to-does-the-right-thing’named ...AndCalculateYield...() and another named ...AndRecordYieldToService(). The methods are smaller so it becomes more obvious how to be specific in their names.
Inline Method the outer method. Now all call sites use the 3 methods directly and you have split out the functionality.

Encapsulation

Another common case is to want to encapsulate something. This usually entails not just removing a clause from the name, but actually encapsulating the behavior so callers can’t see the effect. The usual problem is that the behavior is performed on one of the parameters.

An example is the handling of the local cache in parseXmlAndStoreFlightToDatabaseAndLocalCacheAndShowOnScreenIfVisible(). I’d like to encapsulate that cache and use it as a read-through cache just for performance.

The solution is to find some sequence of refactorings to shift that parameter to be a field. Sometimes this involves creating a new class, splitting a class, or moving the method we are working with to a different class. It also usually involves changing object lifetime and removing references to the value from all callers of the method, often several layers up the stack.

The easiest way to do this is typically to refactor until the method uses everything via a field instead of a parameter, then use the auto-fix to remove unused parameter, then go up the call-stacks and continue removing unused parameter as far as you can.

Here is one common sequence, used when we start with a static method.

Use Introduce Parameter Object. Select just the one parameter you want to encapsulate. Name the class Applesauce and the parameter self.
Use Convert To Instance Method on the static. Select the parameter you just introduced.
Improve the class name (Applesauce) to at least the Honest level.
Go to the caller of the method. Select the creation of the new type. Introduce parameter to push it up to the caller’s caller.
Convert any other uses of the parameter you are encapsulating to use the field off the new class.
When the last usage is gone, use the Autofix for remove unused parameter to remove the now-encapsulated field.
Select any usage of the public field in the calling method and Extract Method the related statements / expression.
Convert to Static on the extracted method, then Convert to Instance Method to move it to the new type.
Repeat 7 & 8 until the calling method no longer uses the field we are encapsulating.
Walk up the stack to the caller of this method. Repeat from step 4. Stop when you get to the initial fetch / creation of the value you are encapsulating.
Move that fetch / creation to be a factory method on the new type (via Extract, Make Static, Convert to Instance).
Repeat from step 4 for any other callers of your original method.
At this point the only references to the value you are encapsulating will be within your new class. The only users of the constructor that takes that value will be factory methods / other constructors.
Convert the constructor to private.
Inline the public property to access the value you are encapsulating. Now all the class methods will just use the field.

The recipe is long, but each step takes 1-2 seconds with proper tooling. No step requires editing code. You can encapsulate even a highly-used value in 2-10 minutes with practice.

You can also encapsulate multiple related values at once. And a variation can be used when you want to split a class or handle similar cases.

Breaking up God Classes

On the surface, breaking up a God Class appears to mean executing the Split Class refactoring many times. In practice, however, it’s a lot more complicated than that. God Classes are problematic not only for the methods of the class but also cause a number of common antipatterns in all the code around them. These two problem areas - the class and the surrounding methods - tend to reinforce each other. It is very difficult to fix either while the other remains broken.

Here are some of the common problems:

The God Class attracts related data. This steals data from surrounding methods, creating utility classes and primitive obsession.
The God class becomes the obvious place for responsibilities related to its data. This makes it hard to see and start other classes, so the surrounding code becomes unclustered.
The God Class becomes a point of coupling between unrelated parts of the system. They start to account for this coupling with special case logic making it difficult to separate them.
Different responsibilities on the God Class share fields, making it hard to pull them apart.
Data gets passed off the God Class via primitive parameters, creating data aliasing issues, some of which are intentional and must be maintained.

That’s why people end up rewriting their God Classes away.

The largest Change Series in Code by Refactoring, Fix God Classes, provides an incremental approach. This can be combined with the Fix Utility Classes Change Series if your codebase has both antipatterns snarled together. The techniques from these Change Series will address the above 4 problems plus several more.

Adopt Now

Help your team adopt Naming as a Process now!

See How it Works

Next up: reveal the intent of each chunk.

Or read the whole Naming as a Process blog series.

Articles: Get to Intent Revealing (Article 6)

Sat, 12 Oct 2019 00:00:00 +0000

Every improvement in our name until now has focused on what our class/method/variable does. We made it honest and then we made it do exactly what we want. The name is both correct and clear.

But it is awkward.

We want to use this name to understand calling methods. It doesn’t yet serve that purpose. The name describes the thing. It doesn’t tell us why we care.

That makes us stumble when reading the caller. We want the names to tell us the purpose of each subcomponent. But right now the name tells us what it does—implementation when we want behavior/intent.

Every time we read a caller, we have to consider whether that implementation will give us our desired intent. That takes mental energy we could better spend elsewhere.

Part 1: Look at the calling methods / use sites

We’ve gotten as far as we can looking at our target to gain insights. Now we need to include the insights from its context.

Read through all the places where this thing is used. Understand it in the flow of other classes and method calls. What happens before, after, or with it?

Most likely the other names around this one will suck too. You need to improve them before you gain any insight. Sometimes insight will happen if the other parts are Honest, but you probably need to get to at least Completely Honest.

When you see all the context items at the Completely Honest level, you may realize that your target actually doesn’t Do the Right Thing. This is rare but it does happen. Fix it.

Part 2: Look for the code’s purpose

As you start to examine the use contexts you will start to see a flow. The target is one step in a larger orchestration. It has a purpose. That purpose is usually at a higher level of abstraction.

Rename the thing to state this purpose. Some common purposes are:

Methods:

What it accomplishes (post-condition), regardless of starting state or process.
Transformation it makes, regardless of beginning or ending states.
Business process it replaces.
Core responsibility the method takes on.
What the method promises to allow callers to safely ignore.

Classes:

The common responsibility of its methods.
What the class is in the real world (Whole Value).
The responsibility that calling context is delegating to the class and assuming the class will take care of. What the caller wants to ignore.

Variables:

How this instance differs from other instances of the same type.
The purpose the context has for this instance. How it is used.

Part 3: Write down the purpose by renaming the target

In our running example, storeFlightToDatabaseAndShowOnScreenIfVisible(flight) becomes beginTrackingFlight(flight). The first name tells us what our method does. The second tells us why we care.

We don’t need to know what tracking a flight entails. We just need to know that this method will take care of initiating that process for us.

We would expect to see a stopTrackingFlight(flight) nearby. And perhaps some query methods to find information about flights that are being tracked.

Play it again

Now repeat this step for another calling context. Your insight may be the same or your insightful name might be jarring in the other context. Often multiple callers are using the same code because of what it happens to do, not because of its purpose.

When this happens, create two methods that share an implementation. To the outside world, they are different things because they express different intent. It just happens that to a computer they do the same thing…for now.

Do the following:

Extract method the entire body of the method.
Rename the extracted (inner) method to the name you had that Does the Right Thing (which you can see in source history).
Duplicate the outer method and edit its name to unique nonsense (do not refactor; you don’t want to update callers).
Rename the unique nonsense to the new purpose.
Edit the call site to use the method with the new purpose.

The reason we hand-edit to nonsense and then rename is so that our tool can catch errors. Hand-editing code is dangerous and something I tend to avoid.

I could duplicate a name or create aliasing problems, especially in the presence of inheritance or global functions with imported namespaces. But these are all problems that the rename refactoring checks for. By hand-editing to unique nonsense, I reduce the chance of making a mistake. And then renaming to the final name ensures that I don’t introduce one at that point.

For a class, the recipe depends on how your IDE does Split Class.

The easy way: use tools

If Split Class supports delegation:

Split Class and select everything. Choose the option to have all callers use the old type and create delegating members.
Rename the inner type to the name you had after Doing the Right Thing.
Copy the file for the outer type (assuming class-per-file).
Hand-change the class name & constructors in the copied file to something guaranteed unique. Nonsense is good here.
Rename the copied class to the new purpose.
Update the construction site to instantiate the new class.
Follow the compile errors, applying the auto-fix each time to change the type of the variable.

The hard way: use a shim

If Split Class doesn’t support delegation:

Create a new class with a unique nonsense name, a single private field of the old type and constructors that match the old type. Use auto-generate members to create delegating members.
Rename the old class back to its Does The Right Thing name to make sure that doesn’t cause conflicts.
Undo the rename refactoring (it was just a test).
Hand-edit the name of the outer class to the name the inner class has (the Intent name for the other context).
Hand-edit the inner class to the Does the Right Thing name.
Update the type and construction of the field in the outer class to use the correct type.
At this point, all call sites will now be using the outer class via the purpose-based name.
Pick up from step 3 in the recipe that assumed Split Class that supports delegation.

This recipe uses a common mini-recipe: introduce a new name for an extracted thing but leave all users using the outer thing.

If we can’t extract the inner thing, then we can get the same result by creating a new outer thing as a shim and then hand-editing the names (not updating call site) to slip it into place.

It also uses a common refactoring test strategy. The most useful part of refactorings is not that they change your code, it is that they tell you what code changes are safe. Sometimes a refactoring won’t do exactly what you want, but you can still use its analysis to verify that the thing you want to do is safe.

We do and undo a rename refactoring to test whether our new names will create any conflicts, even though we execute the name changes by hand so that we can put the shim into place.

Warning: you can get nonsense

Naming by Intent is the easiest one to screw up. If you screw it up you will get a nonsense name. You won’t notice; the name will make sense to you right now because you have the full context. But it will be nonsense the next time you try to use it.

The problem is that this step is intentionally information-losing. We are replacing some of the information about what our thing does with information about why you care to use the thing. We are asking potential users to trust us. And we have to earn that trust. We earn it by using consistently clear names and code that Does the Right Things.

Ways to get nonsense

An extremely popular way to get nonsense is to name a thing by when it is used, rather than why it is used. This gets us right back to calling something preLoad(). One variation on this is to name a method by its initial condition. Ignore initial conditions in method names; they always end in broken abstractions.

Another popular route to nonsense is to create a new concept that is never used anywhere else. One-off abstractions are noise. Create your abstraction by looking at many named entities and use it uniformly.

But perhaps the most popular route to nonsense is to use a CS-y term. The domain of software engineering does not belong in your names unless you are writing a programming language. Even then, domain-specific languages are easier to read.

To avoid nonsense be specific about the context. Clearly state why someone would want to do the things that this class/method is doing. Keep any parts of the Complete and Honest name that make it more obvious when you want to use this thing. Drop the rest.

Adopt Now

Help your team adopt Naming as a Process now!

See How it Works

Next up: see how our intention-revealing names make the right Domain Abstractions obvious.

Or read the whole Naming as a Process blog series.

Articles: Get to Domain Abstraction (Article 7)

Fri, 11 Oct 2019 00:00:00 +0000

Finally we are ready for the most important step in naming. This step is why all of evolutionary design really comes down to “name things well. Continuously.” It is time to correct the domain abstractions we are using and adjust the names.

We currently have a set of names used together. Each one expresses Intent individually. Responsibilities are factored into the right places (each Does the Right Thing). But taken together, the names are a mishmash of ideas. Each expresses itself and its context well, but they don’t create a shared context.

A domain abstraction is just a shared context for some set of code.

At this point, the insights we seek are Whole Values. We want to find generative domain patterns. Concepts that, once they are in place, make the missing code as obvious as the code that is already written.

We won’t necessarily write the missing code yet—we could be wrong about the domain abstraction we see—but we will leave the code in a state where it is obvious where and how to add this code if we need it.

The fundamental process we will do at this step is to find Primitive Obsession, have an insight about a missing Whole Value, and write it down. We will do this mostly mechanically as we want to be able to have insights in code where we don’t yet see the unifying concept.

Finding Primitive Obsession mechanically

We are looking for Primitive Obsession: anywhere that we are trying to describe actions in a high-level domain entirely using concepts in a low-level domain. For example, we might pass around a social security number as a String, rather than as a SocialSecurityNumber. Similarly, we might talk about Set<Cards>, rather than a PlayingCardDeck.

It is entirely possible to spot these based on your own intuition. Use that! However, Primitive Obsession also causes common antipatterns in code. You can look for those in order to learn to spot new kinds of Primitive Obsession.

Here are some of the common patterns I look for. Each identifies some primitive that I am obsessing over.

In sets of classes:

Tight interdependencies with few connections outside the set.
Several methods in one class that use public getters from another.
Classes with similar names:
- Thing / ThingIsValid,
- Repeated prefixes or suffixes: -Transform, -Traversal, Tree-, Tail-.
Classes with CSy or grab-bag names:
- -Manager,
- -Transform.
Names that end with -er, indicating an action rather than a result / object.
Feature envy: obsessing over the methods and properties of another object and calling it all the time.

In sets of methods:

Sets of methods that take the same set of parameters.
Sets of methods that each use the same subset of an object’s fields.
Methods with similar names:
- begin / end / see progress / poll for data,
- create / read / update / destroy,
- source / sink / transform,
- Names which contain near-synonyms.
Chunks of methods which obsess over some variable or small set of variables for several lines (many operations on the same data).
Methods which are often called together (especially common in error handling or creation logic).
Common phrases in the name without a matching noun in the system.

Fields & parameters:

Names that narrow what the thing is, because the variable’s type name cannot (firstName, lastName, SocialSecurityNumber—all on parameters of type String).
Names that narrow or interpret allowed values (rangeInMeters, hardwareModeFlags—both on fields of type int).

Each of these indicates that something is missing in your set of domain abstractions. Other code is coddling that missing abstraction.

Each of these also indicates code that is using an overly-general concept where something more explicit and single-purpose would do.

Part 2: Look for a primitive and the domain concept that would replace it

Every time we see one of the above, we know something is missing. Our goal is to figure out what is missing and create it. This comes in two steps. First we name the primitive, then we name the thing we should use instead.

We don’t need to rename the primitive in the code. We’re about to replace it. Instead we write it down on a notecard or whiteboard. State precisely which primitive we see and what obsessive behaviors we see the code doing over it.

Part 3: Write down by adding new Whole Value that matters

Now we want to write our insight down into code. We need to do the following:

Break the specific concept out of the general concept.
Examine each piece of coddling code.
Break the part ‘../../post/get-to-domain-abstraction’that is related to the new concept out of its context.
Move the related part ‘../../post/get-to-domain-abstraction’to the new concept.

The first 3 steps use refactorings that we already used in earlier phases. Break a concept up by moving from missing to nonsense, then climb the naming levels as desired.

Step 4 uses:

Move Method / Class
Convert to Instance Method
Convert to Static
Convert to Extension Method (if in C#)
Rename

The most common form of rename is to intentionally combine code chunks.

When a primitive has been running around the system for a while, often multiple pieced of code wanted to do the same operation to that primitive. The operation was small (often a 1-line loop with an accumulator variable or a simple conditional). So they just duplicated code inline.

In step 3 we extracted these duplicate chunks into tiny methods. We gave each a good name based on its context (an intention-level name).

In 4 we:

Move them all to the new class.
Use non-overlapping names so that we ensure zero behavior change.
Sort together those with identical implementation.
Examine pairs with identical implementation to see if they also share intent (not all duplicates have the same intent, especially when we are adding a missing domain abstraction).
Any time we find a pair with same implementation and intent, we rename whichever has the less-revealing name to match the name for the other.
Then delete one, leaving the callers sharing code.
Repeat until each pair that shares implementation doesn’t share intent.

It is also common to find pairs that share intent but not implementation. These could be bugs (someone updated one use of the primitive but missed another). They could also be features (the intent is nuanced).

When you find two chunks with similar intent but different implementation:

Rename them to be very similar.
- Use a common prefix followed by something that distinguishes the difference.
- The difference will be implementation, not intent / domain-relevant. That is a smell but better than we had before.
- We can later address that smell by going through the naming process again. Finish this pass first.
Write a pair of tests, one for each chunk. Describe both the common part (with a shared assertion method) and the difference (with two clear, separate asserts).
Optional: combine the two methods into one method with a discriminator variable.

The last step can make things either more or less clear. It can hide the code smell and reduce the probability of fixing, but it can also create a new concept (the discriminator variable itself) which can grow into a valid domain abstraction.

For details on how, see my gist Combine 2 methods into one with a discriminator variable (I’m combining two slightly different implementations of Car.Drive()).

The history shows a complete set of refactorings (17 steps) to implement the re-design without ever violating safety.
I have tests only to show what happens to call sites. I never relied on tests to verify any step.
I would be equally comfortable (and safe) performing this on entirely untested code with thousands of call sites.

And that’s it!

We identified our domain abstraction and wrote it down. At this point our naming is done.

In the real world it probably took me a week or so to get through this whole process (at a total time cost of 30 minutes spread across that week). I find missing names one at a time, create them, and get them up to the honest level. After doing that 4-6 times in one area area I upgrade each of those names up to does the right thing (through complete on the way). After I do that 2-3 times the intent becomes clear and I upgrade the names.

And every so often I see primitives lying around or duplicate sequences of statements that operate on the same variables. When all the names around are intent-revealing, the missing Whole Value becomes obvious. It often requires 2-5 flurries of creating intent-based names before a whole area is intent-revealing.

I introduce a new domain abstraction. Usually, I introduce 3-5 of them in a single quick flurry. The code rapidly changes across the project to use the new abstraction in about 60% of the applicable cases. Then slow change happens over another week or two as the abstraction proves to be valuable. It attracts new operations and cleans up the other applicable cases.

Adopt Now

Help your team adopt Naming as a Process now!

See How it Works

Next up: learn how to apply this whole approach in short steps that each provide value and can be mastered.

Or read the whole Naming as a Process blog series.

Articles: A Learning Path (Article 8)

Thu, 10 Oct 2019 00:00:00 +0000

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!

See How it Works

Deep Roots – Naming as a Process

Articles: Naming as a Process (Article 1)

The solution … annoyingly simplified

The big picture

The source of all technical waste

It’s about risk too

Bugs come from incomplete understanding

Which brings us back to names

Implementing the solution

Adopt Now

Read More

Articles: Get to Obvious Nonsense (Article 2)

Fixing Missing Names

Part 1: Look at Long Things

Part 2: Look for 1 lump that hangs together

Part 3: Write down by extracting it as Applesauce

Applesauce? Really?!

Finding Better Chunks in Long Methods

Look at the Bottom First

Use Binary Search to Read Less

Follow Control Structures

Fixing Misleading Names

Part 1: Look at Names that you are using

Part 2: Look for under-information or misinformation

Part 3: Write down by renaming it to Applesauce

Check it in!

Adopt Now

Read More

Articles: Get to Honest (Article 3)

Making the Name Honest

Part 1: Look inside the body

Part 2: Look for one thing the code does

Part 3: Write down by renaming to a better name

Be specific!

Not just for functions or nonsense names

Adopt Now

Read More

Articles: Get to Completely Honest (Article 4)

Expand the Known

Part 1: Look inside the body

Part 2: Look for one thing the code does that isn’t in the name

Part 3: Write down by adding a clause to the name

Narrow the Unknown

Part 1: Look inside the body or at the name

Part 2: Look for one category of things that the code doesn’t do

Part 3: Write down by adding a clause to the name

Finishing the iteration towards Completely Honest

Really big methods

Things that aren’t methods

Naming by what it does, not by what it is

Adopt Now

Read More

Articles: Get to Does the Right Thing (Article 5)

Part 1: Look only at the name

Part 2: Look for one responsibility to separate

Part 3: Write down by structurally refactoring

Can we get more specific than “structural refactoring???”

Safely moving a responsibility from a method

Encapsulation

Breaking up God Classes

Adopt Now

Read More

Articles: Get to Intent Revealing (Article 6)

Part 1: Look at the calling methods / use sites

Part 2: Look for the code’s purpose

Part 3: Write down the purpose by renaming the target

Play it again

Refactoring methods to share implementation

Refactoring classes to share implementation

The easy way: use tools

The hard way: use a shim

Warning: you can get nonsense

Ways to get nonsense

Adopt Now

Read More

Articles: Get to Domain Abstraction (Article 7)

Finding Primitive Obsession mechanically

Part 1: Look for sets of methods or classes that share some similarity

Part 2: Look for a primitive and the domain concept that would replace it

Part 3: Write down by adding new Whole Value that matters

`Applesauce`? Really?!

Part 3: Write down by renaming it to `Applesauce`