First Do No Harm: Surgical Refactoring (extended edition)

First Do No Harm
Surgical Refactoring
Nell Shamrell-Harrington
@nellshamrell

Section I:
Refactoring
First Do No Harm: Surgical Refactoring @nellshamrell

Refactoring is a change
and changes can go wrong
What is refactoring?

But…it’s not life or death, right?

Software is being integrated into…

Transportation

Transportation
Energy sources

Transportation
Energy sources
Medical Devices

So…is refactoring bad, then?

Refactoring is neither inherently good OR bad

How you do it is what matters

How should I refactor?
2 Common Approaches

2 Common Approaches
1) Edit and Pray

2 Common Approaches
1) Edit and Pray
2) Cover and Modify

2 Common Approaches
1) Edit and Pray
2) Cover and Modify
- “Working Effectively with Legacy Code”

Section II:
Surgical Refactoring

What is surgical refactoring?
Change exactly what we INTEND to change
And ONLY what we intend to change

First do no harm!

Surgical refactoring is a series of
good habits that reduce risk

2 categories of refactoring

1) Necessary refactoring

1) Necessary refactoring
2) Cosmetic refactoring

What is a necessary refactoring?
Need to add something

Code is too inefﬁcient

Code is too inefﬁcient
Blocked from achieving a business need

Necessary refactorings have a
moderate to high risk tolerance

What is a cosmetic refactoring?

No business need to change code

Something about it just bugs us
No business need to change code

Cosmetic refactorings
have a low risk tolerance

What about whitespace refactoring?

Ultimate cosmetic refactoring

Get a style guide
(i.e. Github style guide)

Get a style guide
(i.e. Github style guide)
If whitespace does not violate style
guide, leave it alone!

What’s involved in surgical refactoring?

1) Pre-op: what to do before touching the code

2) Operation: doing the actual refactoring

2) Operation: doing the actual refactoring
3) Recovery: verifying the refactor

lib/do_system_things.rb
class DoSystemThings
def do_the_thing(dir)
system "sed -E -i '' 's/:([[:alnum:]]+)[[:space:]]=>/1:/g'
#{dir}/**/*.rb"
end
end
Thanks, @mikelorant!

Section IV:
Pre-Op

What is involved in pre-op?
Diagnosis
(What exactly does the code do?)

#{dir}/**/*.rb"
end
end

#{dir}/**/*.rb"
end
end Calls Ruby’s system method

#{dir}/**/*.rb"
end
end
Executes sed command with
some flags

#{dir}/**/*.rb"
end
end
Performs a substitution

#{dir}/**/*.rb"
end
end
In a series directories and files

So…do we know what it does?

Map is inﬂuenced by our own
experiences and expectations

Only deﬁnite way of knowing what the code
does is to execute the code itself

Best way to repeatedly execute the
code is through automated tests

#{dir}/**/*.rb"
end
end
Now what does this
system call do?

spec/do_system_things_spec.rb
let(:do_system_things) { DoSystemThings.new }
Instantiate the class

let(:dir) { ‘something’ }
Sample argument
to pass to class

describe ‘making the system call’ do
it ‘calls the Ruby#system method’ do
end
end

expect(do_system_things)
.to receive(:system).with(anything())
end
end
Expect that our instance
of the class

Will receive a system call
with any args
end
end

do_system_things.do_the_thing(dir)
end
end
Call the method

do_system_things.do_the_thing(dir)
end
end
Spec Passes!

"sed -E -i '' 's/:([[:alnum:]]+)[[:space:]]=>/1:/g'
#{dir}/**/*.rb"
end
end
Remove the system call

"sed -E -i '' 's/:([[:alnum:]]+)[[:space:]]=>/1:/g'
#{dir}/**/*.rb"
end
end
Spec Fails!

#{dir}/**/*.rb"
end
end
Put the system call back

#{dir}/**/*.rb"
end
end
Spec Passes!

#{dir}/**/*.rb"
end
end
What return is expected?

#{dir}/**/*.rb"
end
end Rdocs: system method returns true
when the command executes
successfully

context ‘when the method call is successful’ do
it ‘returns true’ do
end
end

expect(do_system_things.do_the_thing(dir)).to eq(true)
end
end
Expect the return from calling
the method on the instance
of the class

end
end
To return true

end
end
Spec Fails!

'sed: directory/*/.rb: No such file or directory'
end
end

let(:directory_name) { ‘some_directory’ }
let(:sub_directory) { ‘some_sub_directory’ }
let(:file) { ‘some_file.rb’ }
end
end
Set the directory, subdirectory, and file names

before do
FileUtils.mkdir_p(File.join(directory_name, sub_directory))
end
end
end
Create directories and sub-directories

before do
path = File
.join(directory_name,subdirectory_name,file_name)
end
end
end
Create the path for
the file

before do
path = File
file = File.new(path, ‘w’)
file.write(‘look, there is something in this file’)
file.close
end
Create the actual file

before do
path = File
file.close
end
Spec Passes!

before do
path = File
file.close
end
it ‘returns true’ do That’s a lot of setup code…

def create_required_directories_and_files(path, filename)
FileUtils.mkdir_p(File.join(path))
file = File.new(File.join(path,file_name), ‘w’)
file.close
end
Takes a path and
file name

file.close
end
Makes the directories

file.close
end
Makes the file

before do
create_required_directories_and_files(
File.join(directory_name,subdirectory_name), file_name
)
end
end
Call the setup
method

before do
)
end
end
Create and pass
the path for the file

before do
)
end
end
Pass the file name

before do
)
end
end
Spec Passes!

before do
)
end
end
after do
FileUtils.rm_rf(directory_name)
end
Remove created
directories and file

before do
)
end
end
after do
FileUtils.rm_rf(directory_name)
end
Spec Passes!

#{dir}/**/*.rb"
end
end
*pause*

#{dir}/**/*.rb"
end
end
sed is a streaming text editor

Find match for this pattern
s/:([[:alnum:]]+)[[:space:]]=>/1:/g'

Replace it with this pattern
s/:([[:alnum:]]+)[[:space:]]=>/1:/g'

def first_regex_match(string)
end
#{dir}/**/*.rb"
end
end

//.match(string)
end
#{dir}/**/*.rb"
end
end

describe ‘what the regex matches’
# FOR REFERENCE: /:([[:alnum:]]+)[[:space:]]=>/
end

let(:string) {‘'}
end

let(:string) {''}
it 'matches a string' do
end
end

let(:string) {''}
expect(do_system_things.first_regex_match(string))
.not_to be_nil
end
end

//.match(string)
end
#{dir}/**/*.rb"
end
end
Returns nil if no successful match

let(:string) {''}
.not_to be_nil
end
end
Means it found a successful match

let(:string) {''}
.not_to be_nil
end
end
first character is ‘:’

let(:string) {‘:'}
.not_to be_nil
end
end
add ‘:’ to string

.not_to be_nil
end
end
Spec Fails!

/:/.match(string)
end
#{dir}/**/*.rb"
end
end
add ‘:’ to regex

/:/.match(string)
end
#{dir}/**/*.rb"
end
end
Spec Passes!

.not_to be_nil
end
end
Next character is alnum
character class

let(:string) {‘:a'}
.not_to be_nil
end
end
Add letter to test string

Spec Fails!
.not_to be_nil
end
end

/:[[:alnum:]]/.match(string)
end
#{dir}/**/*.rb"
end
end
add alnum to regex

end
#{dir}/**/*.rb"
end
end
Spec Passes!

.not_to be_nil
end
end Means character must
appear one or more times

let(:string) {‘:ab'}
.not_to be_nil
end
end
Add character to test string

Spec Passes!
.not_to be_nil
end
end

But…we were expecting a failure…
.not_to be_nil
end
end

end
#{dir}/**/*.rb"
end
end Will return successful match with
only one alnum character

expect(do_system_things.first_regex_match(string)
.to_s).to include(‘:ab’)
end
end
Examining content of string that was
captured by the regex

Spec Fails!
end
end

/:[[:alnum:]]+/.match(string)
end
#{dir}/**/*.rb"
end
end
add + quantifier

/:[[:alnum:]]+/.match(string)
end
#{dir}/**/*.rb"
end
end
Spec Passes!

end
Capture group

end
it ‘captures a group’ do
end

end
expect(do_system_things.first_regex_match(string)[1])
.not_to be_nil
end Testing that match captures
a capture group ([1] references
first capture group)

Spec Fails!
end
.not_to be_nil
end

/:[[:alnum:]]+()/.match(string)
end
#{dir}/**/*.rb"
end
end
Adding empty capture group

/:[[:alnum:]]+()/.match(string)
end
#{dir}/**/*.rb"
end
end
Spec Passes!

end
.not_to be_nil
.to eq(‘ab’)
end
Testing content of capture group

Spec Fails!
end
.not_to be_nil
.to eq(‘ab’)
end

/:([[:alnum:]]+)/.match(string)
end
#{dir}/**/*.rb"
end
end
Placing capture group in
correct place

/:([[:alnum:]]+)/.match(string)
end
#{dir}/**/*.rb"
end
end
Spec Passes!

/:([[:alnum:]]+)[[:space]]=>/.match(string)
end
#{dir}/**/*.rb"
end
end
Fast Forward…
(Adding in tests for rest of characters)

/:([[:alnum:]]+)[[:space]]=>/.match(string)
end
#{dir}/**/*.rb"
end
end We know what this regex does!
‘:ab =>’ matches!

context ‘changing the file’ do
before do
file = File.open(File.join(directory_path,file_name))
file.write(':ab =>')
file.close
end
end
Write sample string to file
(note the space and hash rocket)

it ‘changes the file’ do
original_contents =
File.read(File.join(directory_path,file_name))
end
end
Capture original contents of file

original_contents =
do_system_things.do_the_thing(directory_name)
end
end
Call the method

original_contents =
new_contents = File.read
(File.join(directory_path,file_name))
end
end
Capture new contents of file

original_contents =
expect(original_contents).not_to eq(new_contents)
end
end
Make sure file changes

original_contents =
expect(original_contents).not_to eq(new_contents)
end
end
Spec Passes!

Replace match for the
first pattern with this
second pattern
s/:([[:alnum:]]+)[[:space:]]=>/1:/g'

1:

1:
Escape - so we can use a literal
as the next character

1:
Uses the result of the first capture group
from the first pattern

1:
Adds a literal colon

s/:([[:alnum:]]+)[[:space:]]=>/1:/g'
‘:ab =>’

s/:([[:alnum:]]+)[[:space:]]=>/1:/g'
‘ab:’‘:ab =>’ replace with

let(:orig_string) { “:ab => “}
let(:new_string) { “ab: ‘}
original_contents = File.read(File.join(directory_path,file_name))
new_contents = File.read(File.join(directory_path,file_name))
end
end
Expected content of file
before and after

expect(new_contents).not_to include(orig_string)
expect(new_contents).to include(new_string)
end
end
Verify contents of
modified file

end
end
Spec Passes!

s/:([[:alnum:]]+)[[:space:]]=>/1:/g'
Replace all matches for the
first pattern with the second
pattern

let(:orig_string) { “:ab => :ab =>“}
let(:new_string) { “ab: ab:’}
it ‘changes all matches within the file’ do
end
end
Expected content of
file before and after

let(:orig_string) { “:ab => :ab =>“}
let(:new_string) { “ab: ab:’}
it ‘changes all matches within the file’ do
do_system_things(directory_name)
end
end Spec Passes!

system "sed -E -i '' ’s/:([[:alnum:]]+)[[:space:]]=>/1:/"
#{dir}/**/*.rb"
end
end
Taking out the
global flag

system "sed -E -i '' ’s/:([[:alnum:]]+)[[:space:]]=>/1:/"
#{dir}/**/*.rb"
end
end
Spec Fails!

system "sed -E -i '' ’s/:([[:alnum:]]+)[[:space:]]=>/1:/g"
#{dir}/**/*.rb"
end
end
Putting the flag
back in

#{dir}/**/*.rb"
end
end
Spec Passes!

#{dir}/**/*.rb"
end
end
Next step…add in tests for these flags

# taking the -E flag out
system "sed -i '' ’s/:([[:alnum:]]+)[[:space:]]=>/1:/g"
#{dir}/**/*.rb"
end
end

# taking the -E flag out
system "sed -i '' ’s/:([[:alnum:]]+)[[:space:]]=>/1:/g"
#{dir}/**/*.rb"
end
end
Spec Fails!

# putting the -E flag back in
system "sed E —i '' ’s/:([[:alnum:]]+)[[:space:]]=>/1:/g"
#{dir}/**/*.rb"
end
end

# putting the -E flag back in
#{dir}/**/*.rb"
end
end
Spec Passes!

#{dir}/**/*.rb"
end
end

it ‘does not save a backup copy of the file’ do
# Expect the subdirectory we created to contain only one file
expect(Dir[“#{directory_name}/#{subdirectory_name}/*”]
.count).to eq(1)
end
end

.count).to eq(1)
end
end

.count).to eq(1)
.count).to eq(1)
end
end

.count).to eq(1)
.count).to eq(1)
end
end
Spec Passes!

# adding an extension to the -i flag
system "sed E —i .tmp ’s/:([[:alnum:]]+)[[:space:]]=>/1:/g"
#{dir}/**/*.rb"
end
end

# adding an extension to the -i flag
system "sed E —i .tmp ’s/:([[:alnum:]]+)[[:space:]]=>/1:/g"
#{dir}/**/*.rb”
end
end
Spec Fails!

# removing extension to -i flag
system "sed E —i ‘’ ’s/:([[:alnum:]]+)[[:space:]]=>/1:/g"
#{dir}/**/*.rb"
end
end

# removing extension to -i flag
system "sed E —i ‘’ ’s/:([[:alnum:]]+)[[:space:]]=>/1:/g"
#{dir}/**/*.rb"
end
end
Spec Passes!

#{dir}/**/*.rb"
end
end
We know what this does!

Section V:
Operation

#{dir}/**/*.rb"
end
private
def substitute_command
's/:([[:alnum:]]+)[[:space:]]=>/1:/g'
end
end

system "sed -E -i '' #{substitute_command} #{dir}/**/*.rb"
end
private
's/:([[:alnum:]]+)[[:space:]]=>/1:/g'
end
end

end
private
's/:([[:alnum:]]+)[[:space:]]=>/1:/g'
end
end
Specs Pass!

end
private
's/:([[:alnum:]]+)[[:space:]]=>/1:/g'
end
end Really old regex syntax

end
private
’s/:(w+)s=>/1:/g’
end
end New regex syntax

end
private
’s/:(w+)s=>/1:/g’
end
end Specs Fail!
w != [:alnum]

end
private
's/:([[:alnum:]]+)[[:space:]]=>/1:/g'
end
end Back to the old
regex syntax

Section VI:
Recovery

What do I need to do after refactoring?
Need to know two things decisively

1) Does the behavior still exist?

1) Does the behavior still exist?
2) Is it connected correctly?

What about QA?

Ideally, QA should ﬁnd nothing

What if something goes wrong?

1) Take responsibility - what your code does
in production is your responsibility

2) Evaluate risk of another change
(a change to a change is still a change)

2) Evaluate risk of another change
(a change to a change is still a change)
3) Fix the problem (if you can’t, ﬁnd someone
who can!)

Conclusion
“I’m not a great programmer, I’m just a good
programmer with great habits”
- “Refactoring: Ruby Edition”

Thank You!
Nell Shamrell-Harrington
Software Development Engineer at Chef
@nellshamrell
www.nellshamrell.com
nshamrell@chef.io

First Do No Harm: Surgical Refactoring (extended edition)

More Related Content

Viewers also liked

Similar to First Do No Harm: Surgical Refactoring (extended edition)

More from Nell Shamrell-Harrington

Recently uploaded

First Do No Harm: Surgical Refactoring (extended edition)