Digest: The Clean Coder Book

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.

  • Uncle Bob introduces the concept that some people may not consider programmers as “professionals”, which is the theme of this book
  • Uses “The Challenger” disaster as an example of professionals being ignored and the disaster that followed
  • Professionals must take responsibility for their actions
  • We should be writing tests for every piece of code
  • 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

  • How do you know your code works? You test it!
  • 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

  • “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

  • 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”

  • “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?”

  • Uncle Bob suggests doing “Kata"s

    • one at the start of work

    • One at the end of work

  • You must practice outside of your day job

  • Do katas!

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

  • Peer program!

  • The best way to learn is to teach

  • Professionals take personal responsibility for mentoring their juniors

  • Do not let your juniors flail about

  • If you are writing an accounting system, you should know the accounting field
  • 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
  • Don’t be an insufferable ass

  • Laugh at yourself

  • Don’t promise to “try”

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

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

  • 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
  • It is most important to say no when the stakes are highest

    • The higher the stakes, the more valuable the no
  • 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
  • “Do or do not, there is no try”
  • Negative. Stick to these rules and you’ll be fine
  • “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.

  • Tell tale signs of lack of commitment

    • “Need/should”

    • “Hope/wish”

    • “Let’s”

      • You’ll do it alone, they won’t
  • 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)

  • 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

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

  • Being able to sense your errors is really important

  • 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

  • Don’t code when you are tired

  • Dedication and professionalism are more about discipline then hours

  • Don’t code when worried, distracted or anxious
  • “The Zone” should be avoided

    • You’re on auto pilot and just writing Code
  • Uncle Bob suggests not listening to music while programming
  • 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

  • Do something else, answer emails, jira, etc

  • Or find a pair partner

  • 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

  • Software development is a marathon, not a sprint
  • 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”

  • 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

  • Programming is hard
  • 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?

  • Be gracious when someone offers you help

  • Do not protect your turf

  • Learn how to ask for help

  • 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

  • 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
  • “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
  • 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

  • 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

  • If you have a bunch of tests, the rate at which you’ll introduce bugs should be very very slow
  • 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
  • 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

  • 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

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

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

  • 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
  • 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

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

    • Uses the martial art words for programming
  • “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” 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

  • Contribute to open source projects that would step you outside your comfort zone
  • Use your own time to improve your resume
  • One of the most common issues between programmers and business
  • 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

  • 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

  • Developers always include error room in their estimations
  • Developers want to delay estimating until their comfortable

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

  • There are too many definitions for “acceptance tests”, we’ll define it here
  • 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
  • The purpose of acceptance tests is communication, clarity and precision

    • Developers, stakeholders and testers all understand what the plan for the system behavior is
  • Acceptance tests should always be automated

    • Manual testing is okay elsewhere
  • 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”
  • 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
  • Implementation starts when the acceptance tests are done
  • 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 are not unit tests

  • Unit tests are written by programmers, for programmers

  • Acceptance tests are written by the business for the business

  • 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”
  • The front end should use a separate backend
  • 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

  • If a single tests fails, all is halted until that test is passing again
  • Communication about details is hard, especially between stakeholders and programmers

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.

  • It should be the goal of the development group that QA finds nothing
  • Work together
  • It should be QA’s role to work with business to create the automated acceptance tests
  • 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
  • True coverage, not useless 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

  • 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.

  • 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.

  • Meetings are expensive
  • You do not have to attend every meeting you are invited to.
  • You can simply ask, at an opportune moment, if your presence is still necessary
  • The title is self explanatory ;)
  • 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?

  • 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.

  • 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

  • “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 expands our “mana”

    • We only have so much each day
  • Sleep as many hours as you need to be productive for eight hours
  • Personal thing, don’t over do it
  • Take long walks, converse with friends, stare out a window to regain focus
  • Have some physical based activities / hobbies
  • Read!
  • He explains the Pomodoro technique

    • If you don’t know it, see this
  • When you avoid doing the real work

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

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

  • Keep an open mind about other ideas

  • 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).

  • Businesses view estimates like commitments

  • Developers view estimates like estimates

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

  • Commitment is about certainty

  • 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

  • Draw a distinct between estimates and commitments
  • “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
  • A team of people assemble, discuss a task, estimate the task, and iterate the discussion and estimation until they reach agreement.
  • People discuss the task and vote for how difficult the task is using their fingers

  • Go till majority and most people agree

  • Same as Flying Fingers, but with cards
  • 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 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

  • 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
  • Avoid situations that cause pressure

    • Not entirely but a minimize it
  • We are not honor bound to accept commitments
  • 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
  • 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.”

  • Manage your stress

  • Slow down, think problems through and plot a course

  • Let your team and superiors know if you’re in trouble
  • When things get tough, trust your disciplines
  • Pair!
  • Story about Uncle Bob getting fired and not putting the business first
  • Programmers building walls around their code
  • Break down the walls and the team shares all the code and modules
  • Pair as its the best way to share knowledge

  • All members should be able to pair

  • Story about marketing campaign targeted at “highly intelligent” people where the marketing made a mistake about the brain stem
  • “There is no such thing as a half person”

    • In regards to someone working part time on a project
  • 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

  • It takes time for the team to work together best
  • Moving people off projects will stop the gel process
  • Teams have velocities

    • It is a statistical measure
  • “If the business decides that one project is higher priority than another, it should be able to reallocate resources quickly.”
  • Talks about a CS masters student who couldn’t program

  • Said individuals who taught themselves to program were generally good

  • Story of how a manual was his mentor to learning boolean algebra
  • Story of how these people who installed a big computer in his high school were his mentors, just by him listening
  • Other stories of people teaching him, like how to use a ham radio or multimeter
  • 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
  • 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.”

  • 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

  • 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

  • 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

  • In practice, this obviously can change
  • A craftsman is a professional

  • Craftsmanship is the mindset held by craftsmen

  • Calls it a meme, hahaha

  • You don’t convince people to be craftsman

  • Craftsmanship is contagious

This chapter was not taken notes on purposefully.