org_roam/Books/20250715223949-the_clean_coder.org

:PROPERTIES:
:ID:       EC9D851F-3A2E-4F32-A584-76F6F7A08E30
:TYPE:     Book
:AUTHOR:   Robert C. Martin
:DATE_STARTED: <2025-07-15 Tue>
:DATE_ENDED: <2025-07-27 Sun>
:END:
#+title: the_clean_coder
#+filetags: :books:

* Links:

[[https://medium.com/@stephanie.manwaring/biggest-takeaways-from-each-chapter-of-the-clean-coder-by-robert-c-martin-5e9d1f5ae34][Medium website]]
[[https://codingjourneyman.com/tag/uncle-bob/page/2/][Coding Journey Man]]


* CHAPTER 1: PROFESIONALISM

** Do no harm
No harm should be done to the function of our software. The harm comes about when there are bugs, the QA should find no bugs in the software. If the software is too complex to run without there being bugs, reduce the complexity of the software. Find ways to ensure that the code is designed so that it is easy to test. Aim for 100% test coverage, everything should be tested; automate the testing so you don't waste too much time.

** Do no harm to the structure
It is the structure of your code that allows it to be flexible. If you compromise the structure, you compromise the future. If you want the software to be flexible, you have to flex it. This is done by making easy changes to it all the time, which is known as *merciless refactoring*. 

** Work ethic
Your career is your responsability and nobody else's. The 40 hours at work should be spent on the employers problems, and the extra 20 hours should be spent reading, practicing, learning, and otherwise enhancing your career.

** Know your field
Do you know what a Nassi-Schneiderman chart is? If not, why not? Do you know the difference between a Mealy and a Moore state machine? You should. 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? If you want to be a professional, you should know a sizable chunk of ideas, disciplines, techniques, tools, and terminologies and constantly be increasing the size of that chunk.

Here is a minimal list of the things that every software professional should be conversant with:
• Design patterns. You ought to be able to describe all 24 patterns in the GOF book and have a working knowledge of many of the patterns in the POSA books.
• Design principles. You should know the SOLID principles and have a good understanding of the component principles.
• Methods. You should understand XP, Scrum, Lean, Kanban, Waterfall, Structured Analysis, and Structured Design.
• Disciplines. You should practice TDD, Object-Oriented design, Structured Programming, Continuous Integration, and Pair Programming.
• Artifacts: You should know how to use: UML, DFDs, Structure Charts, Petri Nets, State Transition Diagrams and Tables, flow charts, and decision tables.

** Continuous learning
Read books, articles, blogs, tweets. Go to conferences. Go to user groups. Participate in reading and study groups. Learn things that are outside your comfort zone. If you are a .NET programmer, learn Java. If you are a Java programmer, learn Ruby. If you are a C programmer, learn Lisp. If you want to really bend your brain, learn Prolog and Forth!

** Practice
Doing your daily job is performance, not practice. Practice is when you specifically exercise your skills outside of the performance of your job for the sole purpose of refining and enhancing those skills. More on this later.

** Collaboration
Make a speacial effort to practice, program, plan and design together (not for 100% of your time).

** Mentoring
The best way to learn is to teach.

** Know your domain
It is the responsibility of every software professional to understand the domain of the solutions they are programming. If you are writing an accounting system, you should know the accounting field. If you are writing a travel application, you should know the travel industry. When starting a project in a new domain, read a book or two on the topic. Interview your customer and users about the foundation and basics of the domain. Spend some time with the experts, and try to understand their principles and values.

** Identify with your Employer/Customer
Put yourself in your employer’s shoes and make sure that the features you are developing are really going to address your employer’s needs.

** Humility
Professionals know they are arrogant and are not falsely humble. A professional knows his job and takes pride in his work. A professional is confident in his abilities, and takes bold and calculated risks based on that confidence. A professional is not timid. However, a professional also knows that there will be times when he will fail, his risk calculations will be wrong, his abilities will fall short. Be your own critique and never ridicule others, accept ridicule when deserved and laugh it off when it's not.

* CHAPTER 2: SAYING NO
Professionals are expected to say no. Indeed, good managers crave someone who has the guts to say no. It’s the only way you can really get anything done. (tfb)

If you are a professional, you will pursue and defend your objectives as aggressively as you can, so will your managers/peers. The best possible outcome is the goal that you and your manager share. The trick is to find that goal, and that usually takes negotiation.

The most important time to say no is when the stakes are highest. The higher the stakes, the more valuable no becomes.

Make sure you have documentation (memos) for high stake deliverables/situations (CYA)

* CHAPTER 3: SAYING YES
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.

There are certain phrases used by ourselves and our peers that show a lack of commitment. Here are some common phrases:

• Need\should. “We need to get this done.” “I need to lose weight.” “Someone should make that happen.”
• Hope\wish. “I hope to get this done by tomorrow.” “I hope we can meet again some day.” “I wish I had time for that.” “I wish this computer was faster.”
• Let’s. (not followed by “I . . .”) “Let’s meet sometime.” “Let’s finish this thing.”

Real commitment will have you stating a fact about something you will do with a clear end time. If you rely on someone else to get your job done, do what you can to get what you need to move forward. Don’t let them be a blocker.

Professionals are not required to say yes to everything that is asked of them. However, they should work hard to find creative ways to make “yes” possible.

* CHAPTER 4: CODING
If you are tired or distracted, do not code. You’ll only wind up redoing what you did. Instead, find a way to eliminate the distractions and settle your mind.

Don’t write code when you are tired. Dedication and professionalism are more about discipline than hours. Make sure that your sleep, health, and lifestyle are tuned so that you can put in eight good hours per day.

Spend personal time before work trying to resolve or mitigate personal issues or demands so you can focus your mental energy on being a productive problem solver at work.

Avoid the `flow zone`, rational faculties are diminished in the name of speed. Yes, you may be able to write more code, but you are going to end up giving up the ability to have a holistic view of the problem. You are likely to make decisions that you are going to end up having to go back and reverse.

Be prepared to be interrupted and help someone — it’s the professional thing to do. When you hit writer’s block make sure you are sleeping, eating, and exercising enough. Additionally, read science fiction (or another form of creative consumption other than surfing the internet or watching TV). Lean on other creative consumption outlets to help keep you creative on the job

It is incumbent upon you as a professional to reduce your debugging time as close to zero as you can get. Clearly zero is an asymptotic goal, but it is the goal nonetheless.

Software development is a marathon — not a sprint. Conserve your mental energy during the day.

“Hope” will get you into trouble (“I hope to have it done by…”). Don’t hope. Be direct about your timelines and realistic expectations. If you must, use an estimate/range.

Ask for help and ask to give help (mentor).

Programming is so hard, in fact, that it is beyond the capability of one person to do it well. No matter how skilled you are, you will certainly benefit from another programmer’s thoughts and ideas.

* CHAPTER 5: TDD

1. You are not allowed to write any production code until you have first written a failing unit test.
2. You are not allowed to write more of a unit test than is sufficient to fail—and not compiling is failing.
3. You are not allowed to write more production code that is sufficient to pass the currently failing unit test.

Good tests function like good documentation.
TDD is a discipline that enhances certainty, courage, defect reduction, documentation, and design.
It’s professional to use TDD.

* CHAPTER 6: PRACTICING

It is not your employer’s job to keep your skills sharp for you. That responsability is on YOU.

http://butunclebob.com/ArticleS.UncleBob.TheBowlingGameKata

https://codingdojo.org/

A programming kata is a precise set of choreographed keystrokes and mouse movements that simulates the solving of some programming problem. You aren’t actually solving the problem because you already know the solution. Rather, you are practicing the movements and decisions involved in solving the problem.

Many kata are recorded at http://katas.softwarecraftsmanship.org. Others can be found at http://codekata.pragprog.com. Some of my favorites are:

• The Bowling Game: http://butunclebob.com/ArticleS.UncleBob.TheBowling-GameKata
• Prime Factors: http://butunclebob.com/ArticleS.UncleBob.ThePrimeFactors-Kata
• Word Wrap: http://thecleancoder.blogspot.com/2010/10/craftsman-62-dark-path.html

For a real challenge, try learning a kata so well that you can set it to music. Doing this well is hard. See: https://katas.softwarecraftsmanship.org/?p=71

Programmers can practice in a similar fashion (wasa) using a game known as ping-pong. The two partners choose a kata, or a simple problem. One programmer writes a unit test, and then the other must make it pass. Then they reverse roles. See: https://wiki.c2.com/?PairProgrammingPingPongPattern

Other ways to practice: take on pro-bono work or a pet project, contribute to open source. Practice is something you do when you aren’t being paid.

* CHAPTER 7: ACCEPTANCE TESTING 
** Intro

A company spends over **\$1 million every 6 weeks** on manual testing.
They consider cutting half the tests, risking half the product not working.
**Manual test plans are unsustainable**. Automating tests is far cheaper and more reliable.
**Acceptance tests** should be **automated** using tools like:

FitNesse, Cucumber, Selenium, robot framework, cuke4duke, etc.
These tools make tests **readable and writable by non-programmers**.

Writing acceptance tests is **not extra work** — it's **how you define what "done" means**.
It ensures that stakeholders and developers are **aligned on requirements**.

** Who Writes Them and When?

**Business Analysts (BAs)** often write "happy path" tests.
**QAs** write edge cases and "unhappy paths".
Developers may step in if others can't keep up.
Tests are best written **just before development**, typically during iteration planning.

** Developers are responsible for:

**Connecting** acceptance tests to the system.
**Implementing features** to make tests pass.
Negotiating unclear or flawed tests with authors.
Avoid passive-aggressive compliance; collaborate to refine faulty tests.

** Realistic Expectations (e.g., Timing)

Not all requirements can be absolute (e.g., "must respond in 2 seconds").
Use **statistical assertions** (e.g., 99.5% of requests under 2 seconds).
Developers and stakeholders must **agree on testable, realistic criteria**.

** Acceptance Tests vs Unit Tests

| Feature       | Unit Tests                       | Acceptance Tests                         |
| ------------- | -------------------------------- | ---------------------------------------- |
| Written by    | Developers                       | Stakeholders / BAs / QA / Developers     |
| Purpose       | Specify and verify internal code | Specify and verify business requirements |
| Audience      | Developers                       | Business + Developers                    |
| Scope         | Small units (functions, classes) | Full system (API, UI, etc.)              |
| Primary value | Design documentation             | Requirements documentation               |

Tests are **not redundant** even if they check similar things — their **execution paths and intent differ**.

** Testing GUIs

GUIs are **volatile** (constantly changing), making them hard to test.
Apply **Single Responsibility Principle (SRP)**:

Separate GUI aesthetics from business logic.
**Test through APIs** beneath the GUI whenever possible.
If GUI testing is necessary, use **IDs or abstractions**, not layout-specific logic.
Keep GUI tests **minimal**, as they’re fragile 

** Continuous Integration (CI)
Run **all tests (unit + acceptance)** multiple times per day via CI.
Trigger builds/tests **on every commit**.
A failed build/test is a **"stop everything" event**.
Never ignore broken tests; doing so can lead to **customer-facing bugs**.

* CHAPTER 8: TESTING STRATEGIES
Having a full test automation policy is a feature of professional development teams which is not only composed by unit tests and acceptance tests. The test automation pyramid figure (https://codingjourneyman.com/2014/09/24/the-clean-coder-testing-strategies/) show every test types and their proportion.

Unit tests are written by the programmers for the programmers to ensure that the code is working at the deepest/lowest level. They should execute in milliseconds and target a 100% code coverage (at least 90%).

Component tests are a part of the acceptance tests and check the behavior of individual component. A component encapsulate a specific set of business rules. These kind of tests should be very quick as well because they are decoupled from the other components and should cover about half the system.

Integration tests are required to check the communication between components in order to verify that the “plumbing” has been done correctly. They ensure that the architectural structure of the system is correct. About 20% of the system is covered by integration tests.

System tests are executed at the highest level of the system, from the UI to check the whole application and its construction (load tests are in this category for instance). They check about 10% of the system.

Manual/exploratory tests are done by humans to explore the application for unexpected behaviors. They need the human creativity to hunt possible hidden bugs.

* CHAPTER 9: TIME MANAGEMENT
Attending meetings is important in order to follow the life cycle of your project but you are not required in every one of them. In this case you can politely decline the invitation if your presence is not mandatory. It’s no better to be present and play with your smart-phone because you’re bored or because you’re not involved.

There are also some cases where you can leave a meeting. I know it might look rude to do so but it can happen that a meeting goes not as planned and take much more time that you have anticipated. In a situation like this you can politely ask if your presence is still needed and negotiate your exit. There is nothing worst than a meeting without an agenda and/or without a goal, there is no better way to waste time and energy.

If you use an Agile methodology such as Scrum at work you certainly have to do stand-up meetings every day (mostly at the beginning of the day). Each member of the team should answer the 3 following questions :

    1. What did I do yesterday ?
    2. What am I going to do today ?
    3. What’s in my way ?

And no more, each person should be able to answer these questions in less than one minute. With this short and simple meeting you can easily know if your project is on track or no.

During an iteration planning meeting a development team select and reject backlog items for the new sprint/iteration. The estimates (our next chapter) should be done for every candidate item and if possible some of the acceptance tests. The chosen tasks should be clear and ready for the development phase (coding) and this meeting aims to allow the team to briefly discuss over the items.

Iteration retrospective meeting are designed to share what went wrong and what went right during the last iteration and to present demos to the clients/business. It should not extend 45 minutes, 20 for the retrospective and 25 for the demos which are prepared in advance.

Uncle Bob defines two truths about meetings, finding the correct mix between them for your team can be challenging :

- Meetings are necessary.
- Meetings are huge time wasters.

Writing code is an intellectual exercise that requires long periods of concentration and can be exhausting for your mind. But your focus is not infinite and can be depleted, if you are familiar with Role Playing Game (RPG) see this as an empty mana pool. Unfortunately unlike in RPGs you cannot drink a potion to recharge your concentration in a blink but you can refill it.

Sleeping is the best way to replenish your concentration, a good night of sleep (7~8 hours) can give you enough concentration for an entire day. Coffee is the developer’s best friend and can definitely help you regain a small amount of concentration for a short amount of time but don’t let this beverage send your focus in the wrong direction.

It’s also possible to partially recharge your mana batteries by taking breaks during your day, it allows you to de-focus. If the weather permits it you can go out for a walk, have a conversation with a friends, even meditate if you want. You can also practice a physical discipline, it also demands concentration but not intellectual focus : muscle focus. This type of focus can help you increase your mental focus and give you mana. Programming is a creative discipline then exposing yourself to other people’s creativity (books, comics, movies, etc…) is also helpful to boost your own creativity.

When producing code you will sometimes encounter “blind alleys”. It means that the path you’ve taken leads nowhere, in other word your algorithm does not what you want, your solution does not answer your need. It’s impossible to avoid every “blind alleys” but it’s important to realize when you are in one of them to back out.

What you definitely want to avoid are software “marshes”, “bogs” or “swamps”. Unlike “blind alleys” they don’t stop you, there is always a way forward that looks shorter than the way back but that is not. Sticking to a bad software design is a typical example of a swamp, the more you advance the harder it is to advance and at the end you end up with a colossal “Technical Debt“ without noticing it. It kills a team’s productivity and can sometimes kills and entire project/company because maintenance has become overwhelming. If you discover that you are in a situation like this you should definitely turn back before it’s too late.
* CHAPTER 10: ESTIMATION
    You are honor-bound to decline something you cannot commit to. Commitment is about certainty.
    Professionals know the difference between estimates and commitments.
    Estimates are just guesses. Estimates are ranges (not exact numbers).
    Avoid the word “try”. It’s a loaded term.
    Something to look into is a method like PERT to get a better estimate.
    Professional software developers are very careful to set reasonable expectations despite the pressure to try to go fast.
    Estimating methods: wide band delphi, flying fingers, planning poker.

When you estimate a task, you provide three numbers. This is called trivariate analysis:
• O: Optimistic Estimate. This number is wildly optimistic. You could only get the task done this quickly if absolutely everything went right. Indeed, in order for the math to work this number should have much less than a 1% chance of occurrence. 
• N: Nominal Estimate. This is the estimate with the greatest chance of success. If you were to draw a bar chart, it would be the highest bar,
• P: Pessimistic Estimate. Once again this is wildly pessimistic. It should include everything except hurricanes, nuclear war, stray black holes, and other catastrophes. Again, the math only works if this number has much less than a 1% chance of success.
    
* CHAPTER 11: PRESSURE

A professional developer is calm and decisive under pressure. As pressure grows, she adheres to disciplines knowing that they are the best way to meet the deadlines and commitments pressing on her.
Under pressure? Be sure to manage your commitments, follow disciplines, and keep code clean, communicate, and ask for help.

The best way to stay calm under pressure is to avoid the situations that cause
pressure. That avoidance may not eliminate the pressure completely, but it
can go a long way towards minimizing and shortening the high-pressure
periods.

* CHAPTER 12: COLLABORATION
    Programmers have difficulty working closely with other programmers. That’s no excuse, though. Being a developer means working with people.
    The team owns the code, not the individual
    Professionals pair (and have good pairing habits).
    Pairing is a great way to share knowledge so that people don’t end up in knowledge silos.
    All team members should be able to play another team members’ position in a pinch and should know each other’s code.
* CHAPTER 13: TEAMS AND PROJECTS
    Strive to have a “gelled” team. A gelled team is one that forms relationships, collaborates, and learn each other’s quirks and strengths.
    Gelled teams can work miracles. They plan together, solve together, and get things done.
* CHAPTER 14: MENTORING, APPRENTICESHIP, AND CRAFTSMANSHIP 
Developers often start out by teaching themselves (books, trial & error, copying code).

Without mentorship, they risk missing crucial lessons—like setting expectations, meeting deadlines, and writing maintainable code.

Good mentors matter: they correct mistakes early, model professionalism, and guide juniors through real-world practices.

Software lacks true apprenticeships (unlike medicine, plumbing, or carpentry). New devs need hands-on oversight, not just “figure it out” work.

Professionals should seek mentors and become mentors—help others level up, share best practices, and prevent the cycle of isolated learning.
* APPENDIX A: TOOLING