I recently finished reading the book The Clean Coder, by Uncle Bob and decided to publicly share my notes. To be honest, I wasn’t stoked about this book, as I was told it was not technical. I was pretty skeptical that I’d take anything away and was dreading reading it. I couldn’t have been more wrong. Not only was the book very pleasant to read, but also chock full of great advise that I believe I’ll remember for the entirety of my career. If you have any questions or comments, please don’t hesitate to reach out to me.

Forward

  • Uncle Bob introduces the concept that some people may not consider programmers as “professionals”, which is the theme of this book

Preface

  • Uses “The Challenger” disaster as an example of professionals being ignored and the disaster that followed

Prerequisite Introduction

Chapter 1: Professionalism

Taking responsibility

  • Professionals must take responsibility for their actions

Do No Harm

  • We should be writing tests for every piece of code

QA should find nothing

  • It should not be QA’s job to be the first person to hunt for bugs in your code

  • You should send your code to QA with the expectation that they’ll find nothing

You must know it works

  • How do you know your code works? You test it!

Automate QA

  • Your unit and acceptance tests should be automated

  • Uncle Bob can run his entire suite in about a minute, ensuring he can ship a lot faster

Do No Harm To Structure

  • “You must be able to make changes without exorbitant costs”

  • A great way to practice this is to ensure your software is flexible by making structure changes throughout its life cycle

    • “If you want your software to be flexible, you have to flex it!”

  • This can be called “merciless refactoring”

    • Also the Boy Scout Rule “always check in a module cleaner than when you checked it out”

  • If you have a test suite with 100% coverage, refactoring will be a lot less scary

Work Ethic

  • It is not your employer’s job to give you time to learn

  • Uncle Bob pitches you spend 20 hours a week “reading, practicing, learning and otherwise enhancing your career”

Know Your Field

  • “Do you know what a Nassi-Shneiderman chart is?”

  • “Do you know the difference between Mealy and a Moore state machine”

  • “Could you write a quicksort without looking it up?” “Do you know what the term ‘Transform Analysis’ means?

  • “Could you perform a functional decomposition with Data Flow Diagrams?”

  • “What does the term ‘Tramp Data’ mean?”

  • “Have you heard the term ‘Conascence’?”

  • “What is a Parnas Table?”

Continuous Learning

  • Uncle Bob suggests doing “Kata"s

    • one at the start of work

    • One at the end of work

Practice

  • You must practice outside of your day job

  • Do katas!

Collaboration

  • The second best way to learn is to collaborate with others

  • Peer program!

Mentoring

  • The best way to learn is to teach

  • Professionals take personal responsibility for mentoring their juniors

  • Do not let your juniors flail about

Know Your Domain

  • If you are writing an accounting system, you should know the accounting field

Identify With Your Employer/Customer

  • My employer’s problems are my problems

  • It is easy to fall into an “us vs them” attitude with employer

    • Professionals avoid this at all cost

Humility

  • Don’t be an insufferable ass

  • Laugh at yourself

Chapter 2: Saying No

  • Don’t promise to “try”

    • This makes it sound like you have some reserved energy and effort

    • You don’t. You’re always trying.

Adversarial Roles

  • Sounding conformation isn’t bad

  • Avoiding confrontation at all costs can be bad

    • Asking someone to get X done by Y, when they know they won’t and them just saying yes to be “non-confrontational” is bad

High-Stakes

  • It is most important to say no when the stakes are highest

    • The higher the stakes, the more valuable the no

Being A “Team Player”

  • Don’t get suckered into saying yes to someone higher than or, or anyone at all, just for the attitude of being a team player

Trying

  • “Do or do not, there is no try”

Is Good Code Impossible?

  • Negative. Stick to these rules and you’ll be fine

Chapter 3: Saying Yes

A Language of Commitment

  • “Say. Mean. Do.”

    • There are three parts to making a commitment

  1. You say you’ll do it.

  2. You mean it.

  3. You actually do it.

Recognizing Lack of Commitment

  • Tell tale signs of lack of commitment

    • “Need/should”

    • “Hope/wish”

    • “Let’s”

      • You’ll do it alone, they won’t

What Does Commitment Sound Like?

  • You always have something under your control that you can commit to to help achieve some goal

  • Look for sentences that sound like “I will do X by Y”

    • We’re talking about action

    • There’s no way out of this

    • Either you do it or you don’t (binary ha)

Learning How To Say “Yes”

  • Commit with discipline

    • Need to listen to what people say and how they say it to hear if they are actually capable and committing to doing something

  • Be honest with yourself and others with what can get done by when

Chapter 4: Coding

  • This whole chapter is Uncle Bob’s rules and might be totally disagreed with

  • Being able to sense your errors is really important

Preparedness

  • Coding in intellectually challenging and requires concentration and focus

  • The following must occur

    • Your code must work

      • You must understand your code

      • Be consistent with the language, platform and current system

    • Your code must solve the problem set for you by the customer

    • Your code must fit well into the existing system

      • Do not increase the system’s rigidity, fragility or opacity oft he system

      • Dependencies must be well managed

      • In short, follow solid principles

    • Your code must be readable by other programmers

      • Not just comments, but have your code reveal its intent

      • Might be the most difficult thing a programmer has to do

  • If you’re too tired or distracted don’t code, as you will not follow these rules and produce bugs

3 AM Code

  • Don’t code when you are tired

  • Dedication and professionalism are more about discipline then hours

Worry Code

  • Don’t code when worried, distracted or anxious

The Flow Zone

  • “The Zone” should be avoided

    • You’re on auto pilot and just writing Code

Music

  • Uncle Bob suggests not listening to music while programming

Interruptions

  • When you’re interrupted if you were “in the zone” you may be rude and lose all what you were working on

  • Pairing can help with dealing with interruptions, as there’s two of you to recall the state

  • TDD is another tool to help with interruptions, the tests holds the contexts of what you’re working on

  • There will always be interruptions to distract you

    • Remember you may be the person interrupting someone asking for help

  • A professional attitude is polite and willingness to help

Writer’s Block

  • Do something else, answer emails, jira, etc

  • Or find a pair partner

Debugging Time

  • For some reason, developers don’t think of debugging time as coding time

  • You’ll spend less time debugging if you write tests and practice TDD

Pacing Yourself

  • Software development is a marathon, not a sprint

Know When To Walk Away

  • Stuck on a problem? Leave it be.

  • He talks about thinking about problems when driving home, in the shower and what not as he “walked away”

Being late

  • You’ll be late at some point

  • There are many approaches

    • Hope

    • Rushing

    • Overtime

    • False Delivery

  • All of these are not very smart, with the exception of potentially overtime in some specific scenarios

    • Only do overtime if you can personally afford it

    • It is short term, two weeks or less

    • Your boss has a fall-back plan in case the overtime effort fails

Help

  • Programming is hard

Helping Others

  • It is our responsibility to be available to others when they ask for help

  • Block out time just for you

  • Be conscious of the status of your team mates

    • Are they working through something tough

    • Do they need help?

Being Helped

  • Be gracious when someone offers you help

  • Do not protect your turf

  • Learn how to ask for help

Mentoring

  • The training of less experienced programmers is the responsibility of those who have more experience

  • Nothing can bring a less experienced programmer further and faster than effective mentoring by seniors

Chapter 5: Test Driven Development

  • Uncle Bob really illustrates how the cycle time, as in the time it takes to iterate from working on a test that fails writing the code and having that test passes, should be short

The Jury Is In

  • “I don’t think surgeons should have to defend hand-washing and I don’t think programmers should have to defend TDD”

  • If you’re a professional then you must know your code works

    • To do this you must write tests

The Three Laws of TDD

  • I’m going to write the three laws here verbatim, as they are super eye opening

    • You are not allowed to write any production code until you have first written a failing unit test.

    • You are not allowed to write more of a unit test than is sufficient to fail and not compiling is failing.

    • You are not allowed to write more production code that is sufficient to pass the currently failing unit test.

  • These three laws lock you into a cycle, that you can get down to thirty seconds long

  • The production code and the test code grow together, complimenting each other

The Litany of Benefits

Certainty

  • If you practice TDD, you’ll write many many tests

  • Your QA process can be automated, then pass your product to the real QA team and nothing should be wrong

  • Your automated QA cycle should be very quick to run, so you can release confidently very quickly

Defect Injection Rate

  • If you have a bunch of tests, the rate at which you’ll introduce bugs should be very very slow

Courage

  • If you write tests, you’ll feel confident in refactoring or cleaning your code

    • Your tests act as a check, ensuring your changes are still correct

Documentation

  • Think about when you write in a frame work, you check their documentation and code examples right?

  • Your unit tests should provide examples of instantiating every object, calling every function and should act as great living documentation, as they’ll fail when they will no longer correct

Design

  • When you follow the three laws, you’ll figure out where your code is coupled based on what tests are more difficult to write by following the laws

    • Ie if the function your writing the tests for calls another function, you’ve just discovered a dependency

  • If you don’t follow the three laws, there is no force keeping your coupling in check

The Prossenional Option

  • TDD is a discipline that enhances certainty, courage, defect reduction documentation and design

  • How can it be considered professional to not use it?

What TDD Is Not

  • It is not a silver bullet

  • No guarantee of these benefits

  • Sometimes following the three laws will be impractical or inappropriate

    • It is rare but possible

Chapter 6: Practicing

The Coding Dojo

  • Talks about using Katas to practice

    • Training your body and fingers to react and be as efficient as possible

  • Also talks about writing Conway’s game of life as a Kata

Kata

  • A “kata” is a precise set of choreographed movements that simulates one side of combat

    • Uses the martial art words for programming

Wasa

  • “Wasa” practicing in pairs

    • One partner plays the role of the aggressor, the other the defender and then they swap

  • This can be done in programming called “ping-pong”

    • One writes a unit tests, the other makes it pass and reverse

Randori

  • “Randori” free form combat

    • Similar to wasa but with many people and a twist

  • With the screen projected on the wall, one person write sa test and then sits down

    • The next person makes the test pass and then writes a new test

    • People line up as they feel so

Broadening Your Experience

Open Source

  • Contribute to open source projects that would step you outside your comfort zone

Practice Ethics

  • Use your own time to improve your resume

Chapter 7: Acceptance Testing

Communicating Requirements

  • One of the most common issues between programmers and business

Premature Precision

  • Business people want to know exactly what they are going to get before they authorize a project

  • Developers want to know exactly what they are supposed to deliver before they estimate

The Uncertainty Principle

  • Things appear different on paper than they do in a working system

  • When a business person sees what they asked for, in the requirement, they’ll have a better idea of what they really want and its usually not what they’re seeing

  • What the business sees, gives them more information then they had before

Estimation Anxiety

  • Developers always include error room in their estimations

Late Ambiguity

  • Developers want to delay estimating until their comfortable

  • Stake holders can find it easy to be a wordsmith and get developers to agree

Acceptance Tests

  • There are too many definitions for “acceptance tests”, we’ll define it here

The Definition of “Done”

  • When a developer says there “done”, what does that mean?

    • It should mean all the code has been written, all the tests have been written, the tests pass and QA and stakeholders have accepted it

Communication

  • The purpose of acceptance tests is communication, clarity and precision

    • Developers, stakeholders and testers all understand what the plan for the system behavior is

Automation

  • Acceptance tests should always be automated

    • Manual testing is okay elsewhere

Extra Work

  • It looks like a lot of extra work to run acceptance tests, but in reality its the only way for us programmers to know what is “done”

Who Writes Acceptance Tests, And When?

  • In an ideal world the stakeholders and QA would collaborate to write these tests and the developers would review them for consistency

  • If the developers write these tests, ensure the developer that writes the tests are not the ones implementing the feature

  • Typically, “business analysts” write the happy path version of the tests, as they have business value

    • QA will typically write the unhappy path tests, boundary conditions, exceptions and corner cases

  • These acceptance tests are written as late as possible to follow the principle of “late precision”

    • Typically a few days before the feature is implemented. After the features have been selected for the next iteration or sprint

The Developer’s Role

  • Implementation starts when the acceptance tests are done

Test Negotiation And Passive Aggression

  • A professional developer negotiates with the test author for a better test

  • Never do explicitly what the test says if you disagree with it

Acceptance Tests and Unit Tests

  • Acceptance tests are not unit tests

  • Unit tests are written by programmers, for programmers

  • Acceptance tests are written by the business for the business

GUIs and Other Complications

  • Is hard to specify GUIs up front

  • When writing acceptance tests for GUI you have to take advantage of the underlying abstractions that don’t change very frequently

    • EX: “there may be several buttons on a page. Rather than creating tests that click on those buttons based on their positions on the page, you may be able to click on them based on their names. Better yet, perhaps they each have a unique ID that you can use”

Testing Through The Right Interface

  • The front end should use a separate backend

Continuous Integration

  • Make sure all unit tests and acceptance tests run several times per day in CICD system

  • Have this system be triggered every time a commit is made

Stop The Presses

  • If a single tests fails, all is halted until that test is passing again

Conclusion

  • Communication about details is hard, especially between stakeholders and programmers

Testing Strategies

A lot of verbatim text will be here, as I want to be absolutely certain what Uncle Bob considers each test to be is very clear.

QA Should Find Nothing

  • It should be the goal of the development group that QA finds nothing

QA Is Part Of The Team

  • Work together

QA As Specifiers

  • It should be QA’s role to work with business to create the automated acceptance tests

QA As Characterizers

The Test Automation Pyramid

  • He goes over the tests a project should have and the coverage

    • This coincides with what Lyft talked to us about unit test importance at Gluecon back in 2018

Unit Tests

  • True coverage, not useless tests

Component Tests

  • Component tests are written by QA and Business with assistance from development.

  • They are directed more towards happy-path situations and very obvious corner, boundary, and alternate-path cases.

  • The vast majority of unhappy-path cases are covered by unit tests and are meaningless at the level of component test

Integration Tests

  • These tests only have meaning for larger systems that have many components

  • Integration tests are choreography tests.

  • They do not test business rules.

  • Rather, they test how well the assembly of components dances together.

  • They are plumbing tests that make sure that the components are properly connected and can clearly communicate with each other.

System Tests

  • These are automated tests that execute against the entire integrated system.

  • They are the ultimate integration tests.

  • They do not test business rules directly. Rather, they test that the system has been wired together correctly and its parts interoperate according to plan.

  • We would expect to see throughput and performance tests in this suite.

Chapter 9: Time Management

Meetings

  • Meetings are expensive

Declining

  • You do not have to attend every meeting you are invited to.

Leaving

  • You can simply ask, at an opportune moment, if your presence is still necessary

Have An Agenda And A Goal

  • The title is self explanatory ;)

Stand Up Meetings

  • Legitimate stand

    • No one getting comfy and happy with long meeting

  • Each person must answer all these questions and it should take each person no more than one minute

    • What did I do yesterday?

    • What am I going to do today?

    • What’s in my way?

Iteration Planning

  • Most difficult meetings in Agile to do well

  • Iteration planning meetings are meant to select the backlog items that will be executed in the next iteration.

  • Estimates should already be done for the candi-date items.

Iteration Retrospective And DEMO

  • These meetings are conducted at the end of each iteration.

  • Team members discuss what went right and what went wrong

  • No more than 20 minutes to reflection and 25 minutes for demo to stakeholders

Arguments/Disagreements

  • “Any argument that can’t be settled in five minutes can’t be settled by arguing.”

  • Big arguments should be settled by both parties explaining their side to peers and then a vote

Focus Manna

  • Focus expands our “mana”

    • We only have so much each day

Sleep

  • Sleep as many hours as you need to be productive for eight hours

Caffeine

  • Personal thing, don’t over do it

Recharging

  • Take long walks, converse with friends, stare out a window to regain focus

Muscle Focus

  • Have some physical based activities / hobbies

Input Versus Output

  • Read!

Time Boxing and Tomatoes

  • He explains the Pomodoro technique

    • If you don’t know it, see this

Avoidance

Priority Inversion

  • When you avoid doing the real work

  • Disregard your personal fears and desires and execute tasks in priority order

Blind Alleys

  • Avoid getting so blinded by the idea that you can’t abandon it and turn around

  • Keep an open mind about other ideas

Marshes, Bogs, Swamps And Other Messes

  • Blind alleys are avoidable, unlike these

  • Messes impede your progress, but you can still make progress through sheer brute force. Messes are worse than blind alleys because you can always see the way forward, and it always looks shorter than the way back (but it isn’t).

Chapter 10: Estimation

What Is An Estimate?

  • Businesses view estimates like commitments

  • Developers view estimates like estimates

A Commitment

  • Professionals don’t make commitments unless they know they can achieve them

  • Commitment is about certainty

An Estimate

  • An estimate is a guess without any commitment implied

  • We estimate, as we don’t know how long it will take

  • An estimate is not a number, but rather a distribution

Implied Commitments

  • Draw a distinct between estimates and commitments

PERT

  • “Program Evaluation and Review Technique” = PERT

  • Whenever you estimate a task you provide three numbers

    • “O”: optimistic estimate

      • If everything goes right

    • “N”: normal estimate

      • Greatest chance of success

    • “P”: pessimistic estimate

      • This is if everything goes wrong

  • Using these three numbers calculate the mean, which is represented by “μ”, the greek letter mu

    • The average

  • Calculate standard deviation, which is represented by “σ”, the greek letter sigma

    • A measurement of how uncertain a task is

Estimating Tasks

Wideband Delphi

  • A team of people assemble, discuss a task, estimate the task, and iterate the discussion and estimation until they reach agreement.

Flying Fingers

  • People discuss the task and vote for how difficult the task is using their fingers

  • Go till majority and most people agree

Playing Poker

  • Same as Flying Fingers, but with cards

Affinity Estimation

  • Tasks are sorted by group, without talking, based on how long the tasks will take

    • Discuss after sorting stops

  • Draw lines between cards to separate into five buckets

    • Traditional fib numbers [1, 2, 3, 5, 8]

The Law of Large Numbers

  • The law states that “According to the law, the average of the results obtained from a large number of trials should be close to the expected value, and will tend to become closer as more trials are performed.”

  • Uncle Bob states that estimating small tasks will have this law apply

Chapter 11: Pressure

  • If your doctor was under pressure, would you want him to forget his training and how he acts from day to day?

    • Then why do software engineers, under pressure, stop writing tests

Avoiding Pressure

  • Avoid situations that cause pressure

    • Not entirely but a minimize it

Commitments

  • We are not honor bound to accept commitments

Staying Clean

  • Do not succumb to the temptation to create a mess in order to move quickly

  • “Quick and dirty” is an oxymoron

    • Dirty always means slow

Crisis Discipline

  • I"f you follow the discipline of Test Driven Development in noncrisis times but abandon it during a crisis, then you don’t really trust that TDD is helpful.”

  • “If you keep your code clean during normal times but make messes in a crisis, then you don’t really believe that messes slow you down.”

  • “If you pair in a crisis but don’t normally pair, then you believe pairing is”

  • “Choose disciplines that you feel comfortable following in a crisis.”

Handling Pressure

Don’t Panic

  • Manage your stress

  • Slow down, think problems through and plot a course

Communicate

  • Let your team and superiors know if you’re in trouble

Rely On Your Disciplines

  • When things get tough, trust your disciplines

Get Help

  • Pair!

Chapter 12: Collaboration

Programmers Versus People

Programmers Versus Employers

  • Story about Uncle Bob getting fired and not putting the business first

Programmers Versus Programmers

Owned Code
  • Programmers building walls around their code
Collective Ownership
  • Break down the walls and the team shares all the code and modules
Pairing

  • Pair as its the best way to share knowledge

  • All members should be able to pair

Cerebellums

  • Story about marketing campaign targeted at “highly intelligent” people where the marketing made a mistake about the brain stem

Chapter 13: Team and Projects

Does It Blend?

  • “There is no such thing as a half person”

    • In regards to someone working part time on a project

The Gelled Team

  • Team forming relationships and learning each other’s quirks, strengths and weaknesses

  • Ratio of programmers to testers and analysts can vary, but 2:1 is a good number

Fermentation

  • It takes time for the team to work together best

Which Came First, the Team or the Project?

  • Moving people off projects will stop the gel process

But How Do You Manage That?

  • Teams have velocities

    • It is a statistical measure

The One Project Owner Dilemma

  • “If the business decides that one project is higher priority than another, it should be able to reallocate resources quickly.”

Chapter 14: Mentoring, Apprenticeship, And Craftsmanship

Degrees of Failure

  • Talks about a CS masters student who couldn’t program

  • Said individuals who taught themselves to program were generally good

Mentoring

Digi-Comp I, My First Computer

  • Story of how a manual was his mentor to learning boolean algebra

The ECP-18 In High School

  • Story of how these people who installed a big computer in his high school were his mentors, just by him listening

Unconventional Mentoring

  • Other stories of people teaching him, like how to use a ham radio or multimeter

Hard Knocks

  • Talks about getting fired even after he got a letter learning about his probation

    • Convinced the letter was a formality and the decision was already made

Apprenticeship

  • Doctors do internships for many many years

    • Just like painters, plumbers, electricians

  • “Somehow the software development industry has gotten the idea that program-mers are programmers, and that once you graduate you can code.”

Software Apprenticeship

Masters

  • Usually 10+ years of experience

  • Many different systems, languages and operating systems

  • Can lead and coordinate multiple teams

  • Proficient designer and architecture

  • Read, study, practice and teach

Journeymen

  • Competent and energetic

  • Learn to work well in a team and become team leaders

  • Knowledgeable about current technology, lack experience with diverse systems

  • Tend to know one language, platform or system

  • Average is five years

  • Supervised by masters

  • Code is scrutinized

  • Autonomy is growing

  • Supervision will be less direct

Apprentices/Interns

  • Graduates start here

  • No autonomy

  • Very closely supervised by journeymen

  • At first take no solo tasks and just provide assistance journeymen

  • Very intense pair programming

  • Journeymen are the teachers

  • Ought to last a year

  • Masters examine the apprentice both by interview and reviewing their accomplsihments

The Reality

  • In practice, this obviously can change

Craftsmanship

  • A craftsman is a professional

  • Craftsmanship is the mindset held by craftsmen

  • Calls it a meme, hahaha

Convincing People

  • You don’t convince people to be craftsman

  • Craftsmanship is contagious

Tooling

This chapter was not taken notes on purposefully.