the_clean_coder_summary.md

The Clean Coder

Foreword

Blamestorming - the ultimate blame game within the working environment.

Professionals set boundary between their work and private time.

Preface

Being a professional..."is a willingness to accept the dire responsibility of being a craftsman and an engineer. That responsibility includes working well and working clean. It includes communicating well and estimating faithfully. It includes managing your time and facing difficult risk-rewarding decisions."

"But that responsibility includes one other thing - one frightening thing. As an engineer, you have a depth of knowledge about your systems and projects that no managers can possibly have. With that knowledge comes the responsibility to act."

Chapter 1 - Professionalism

Be Careful What You Ask For

"What would happen if you allowed a bug to slip through a module, and it cost your company $10,000? The nonprofessional would shrug his shoulders, say "stuff happens," and start writing the next module. The professional would write the company a check for $10,000."

"...professionalism is all about taking responsibility."

Taking Responsibility

"...shipping without testing the routine had been irresponsible. The reason I neglected the test was so I could say I had shipped on time."

First, Do No Harm

Do No Harm to Function

• "Software is too complex to create without bugs. Unfortunately that doesn't let you off the hook."

• "You cannot simply keep making the same errors over and over. As you mature in your profession, your error rate should rapidly decrease towards the asymptote of zero."

QA Should Find Nothing

• "Releasing code to QA that you don't know it works is unprofessional."

You Must Know It Works

• "How can you know your code works? That's easy. Test it. Test it again. Test it up. Test it down. Test it sever ways to Sunday."

• "...automate your tests..."

Automated QA

• "So, at the very least, your automated test should tell you that the system is very likey to pass QA."

Do Not Harm to Structure

• "The true professional knows that delivering function at the expense of structure is a fool's errand. 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 your software to be flexible, you have to flex it!

  The only way to prove that your software is easy to change is to make easy changes to it. And when you find that the changes aren't as easy as you thought, you refine the design so that the next change is easier.

  When do you make this easy changes? All the time! Every time you look at a module you make small, lighweight changes to it to improve its structure. Every time you read through the code you adjust the structure."

• This approach is the path of merciless refactoring AKA the Boy Scout rule "Always check in a module cleaner that when you checked it out."

• "It all comes back to the tests. If you have an automated suite of tests that covers virtually 100% of the code, and if that suite of tests can be executed quickly on a whim, then you simply will not be afraid to change the code. How do you prove you are not afraid to change the code? You change it all the time."

• "Professional developers are so certain of their code and tests that they are maddeningly casual about making random, opportunistic changes."

• "They treat software the way a sculptor treats clay - they continuously shape and mold it."

Work Ethic

• "Your career is your responsibility. It is not your employer's repsonsibility to make sure you are marketable."

• "Some employers are willing to buy you books and send you to training classes and conferences. That's fine, they are doing you a favor. But never fall into the trap of thinking that this is your employer's responsibility."

• "You should plan on working 60 hours per week. The first 40 are for your employer. The remaining 20 are for you. During this remaining 20 hours you should be reading, practicing, learning, and otherwise enhancing your career."

• "Perhaps you don't want to make that kind of commitment. That's fine, but you should not then think of youself as a professional. Professionals spend time caring for their profession."

• "... But remember, those 20 hours are for you. ... During that 20 hours you should be doing those things that reinforce your passion. Those 20 hours shold be fun!"

Know Your Field

• "Here is the minimal list of the things that every software professional sould be conversant with:

  • Design patterns
  • Design principles
  • Methods
  • Disciplines
  • Artifacts"

Continuous Learning

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

Collaboration

• "Professional software developers make a special effort to program together, practice together, design and plan together. By doing so they learn a lot from each other, and they get more done faster with fewer errors."

Mentoring

• "...the benefit of teaching is strongly in favor of the teacher.

  By the same token, there is no better way to bring new people into an organization than to sit down with them and show them the ropes."

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

• "It is the worst kind of unprofessional behavior to simply code from a spec without understanding why that spec makes sense to the business."

Identify with Your Employer/Customer

• "Your employer's problems are your problems."

• "It is easy to fall into an us versus them attitude with your employer. Professionals avoid this at all costs."

Humility

• The professional... "there will be times when he will fail...he'll look in the mirror and see an arrogant fool smiling back at him."

Chapter 2 - Saying No

• "And certainly I should have continued to say "no" instead of getting in line behind our team lead."

• "Professionals speak truth to power. Professionals have the courage to say not to their managers."

• "Slaves are not allowed to say no. Laborers may be hesitant to say no. But 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."

Adversarial Roles

• "But don't you have to do what your manager says? No, your manager is counting on you to defend your objectives as aggressively as he defends his. That's how the two of you are going to get to the best possible outcome.

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

What about the Why?

• "...why is a lot less important than the fact. The fact is that the login page will require two weeks. Why it will take two weeks is just a detail."

• "Providing too much detail can be an invitation for micro-management."

High Stakes

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

• "Firing me isn't going to change the estimate..."

Being a "Team Player"

• "Being a team player means playing your position as well as you possibly can, and helping out your teammates when they get into a jam. A team-player communicates frequently, keeps an eye out for his or her teammates, and executes his or her own responsibilities as well as possible."

Trying

• "The promise to try is an admission that you've been holding back, that you have a reservoir of extra effor that you can apply."

Passive Aggression

• From Wikipedia: "Passive–aggressive behavior is characterized by indirect resistance to the demands of others and an avoidance of direct confrontation."

• This type of behaviour can be idetified by the following behavioral patterns:

• clear communication
• evading problems
• fear of intimacy or competition
• making excuses
• blaming others
• obstructionism
• "playing the victim"
• feigning compliance with requests
• sarcasm
• backhanded compliments
• and hiding anger

The Cost of Saying Yes

The following quotes are excerpts from the blog post writtent by John Blanco.

• "And then it's happening. Despite years of constant reminders that every feature a client asks for will always be more complex to write than it is to explain, you go for it."

• "If you want to be a better developer, you must always keep this inevitably in mind: The client will always extend the deadline."

• "Rush to complete, slow to market"

• Tell the developer the app is simple
• Add features by faulting the team for not recognizing their necessity
• Push the deadline. Over and over.

Code Impossible

• "What we all have to realize is that saying yes to dropping our professional disciplines is not the way to solve problems. Dropping those disciplines is the way to create problems."

• "Is good code impossible? Is professionalism impossible?"

Chapter 3 - Saying Yes

• "...I waited in a tree for the CEO of the company. We had a big oak tree outside the front of the building. I climbed it and waited for his Jaguar to pull in. I met him at the door an asked for a few minutes. He obliged.

  I told him we really needed to start up the ER project again. I told him I was sure it could make money. He surprised me by saying, 'OK Bob, work up a plan. Show me how I can make money. If you do, and I believe it, I'll start up ER again.'

  I hadn't expected that. I had expected him to say, 'You're right Bob. I'm going to start the project up again, and I'm going to figure out how to make money at it.' He put the burden back on me. And it was a burden I was ambivalent about. After all, I was a software guy not a money guy. I wanted to work on the ER project, not be responsible for profit and loss. But I didn't want to show my ambivalence. So I thanked him and left his office with these words:

  'Thanks Russ. I'm commited...I guess.'""

A Language of Commitment

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

• Need/should
• Hope/wish
• Let's

What Does Commitment Sound Like?

• "...binary is possible - you either get it done, or you don't."

• "Finding out if it can be done can be one of the action to commit to!"

Learning How to Say "Yes"

• "It's easy to say you'll get a lot done on the weekends, it's a lot harder to actually muster enough energy to do high-quality work.

  Professionals know their limits. They know how much overtime they can effectively apply, and they know what the cost will be."

Chapter 4 - Coding

• "Being able to sense your errors is really important. Not just in typing, but in everything. Having error-sense means that you very rapidly close the feedback loop and learn from your errors all the more quickly.

  ...

  I've found that in each case that the key to mastery is confidence and error-sense."

Preparedness

• "... coding require you to juggle many competing factors at once.

  1. First, your code must work
  2. Your code must solve the problem set for you by the customer.
  3. Your code must fit well into the existing system.
  4. Your code must be readable by other programmers.

  If you are tired and 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."

3 AM Code

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

Worry Code

• "Have you every gotten into a big fight with your spouse or friend, and then tried to code? Did you notice that there was a background process running in your mind trying to resolve, or at least review the fight?"

The Flow Zone

• "Here's a little hint from someone whose been there and back: Avoid the Zone. ... It's really just a mild meditative state in which certain rational faculties are diminished in favor of a sense of speed."

• "...The problem is that you lose some of the big picture while you are in the Zone, so you will likely make decisions that you will later have to go back and reverse."

Writer's Block

• "Sometimes the code just doesn't come. I've had this happen to me and I've seen it happen to others. You sit at the workstation and nothing happens."

Creative Input

• "I learned a long time ago that creative output depends on creative input."

Debugging

• "For some reason software developers don't think of debugging time as coding time."

Pacing Yourself

• "Software development is a marathon, not a sprint."

Know When to Walk Away

• "Can't go home till you solve this problem? Oh yes you can, and you probably should!"

• "Learn the patterns of creativity and brilliance, and take advantage of them rather than work against them."

Driving Home

• "One place that I have solved a number of problems is my car on the way home from work."

The Shower

• "I have solved an inordinate number of problems in the shower." :)

Being Late

• "Do not incorporate hope into your estimates!"

Hope

• "Hope is the project killer."

Rushing

• "There is no way to rush. You can't make yourself code faster. You can't make yourself solve problems faster."

Overtime

• "Overtime will certainly fail if it goes on for more than two or three weeks."

False Delivery

• "Of all unprofessional behaviours that a programmer can indulge in, perhaps the worst of all is saying you are done when you know you aren't."

Help

• "Programming is hard. The younger you are the less you believe this. After all, it's just a bunch of if and while statements. But as you gain experience you begin to realize that the say you combine those if and while statements is critically important. You can't just slather them together and hope for the best. Rather, you have to carefully partition the system into small understandable units that have as little to do with each other as possible - and that's hard.

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

Helping Others

• "You should be consious of that status of your teammates."

Being Helped

• "Do not protect your turf. Do not push the help away because you are under the gun."

• "It is unprofessional to remain stuck when help is easily accessible."

• "Most of us got into programming because we prefer to deeply focus on sterile minutia, juggle lots of concepts simultaneously, and in general prove to ourselves that we have brains the size of a planet, all while not having to interact with the messy complexities of other people."

Mentoring

• "Training courses don't cut it. Books don't cut it. Nothing can bring a young software developer to high performance quicker than his own drive, and effective mentoring by his seniors."

Chapter 5 - Test Driven Development

The Jury Is In

• "How can you get automated unit tests with very high coverage without practicing TDD?"

The Three Laws of 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.
3. You are not allowed to write more production code that is sufficient to pass the currently failing unit test.

• "The two code streams grow simultaneously into complementary components."

The Litany of Benefits

Certainty

• "...I am nearly certain that the chagnge I made didn't break anything. How ceertain is "nearly certain"? Certain enough to ship!

Defect Injection Rate

• "...I know my defect injection rate is very low."

Courage

• "Why don't you fix bad code when you see it? Your first reaction upon seeing a messy function is 'This is a mess, it needs to be cleaned.' Your second reaction is 'I'm not touching it!.' Why? Because you know that if you touch it you risk breaking it; and if you break it, it becomes yours."

Documentation

• "...if you want to know how to use code you need to read code."

• "There will be a unit test that describes how to call every function in the system every way that those functions can meaningfully be called."

Design

• "...the need to test first forces you to think about good design."

• "But the tests you write after are defense. The tests you write first are offense."

What TDD Is Not

• "...is not a religion or magic formula."

• "Following the three laws does not guarantee any of those benefits. You can still write bad code even if you write your tests first. Indeed, you can write bad tests."

Chapter 6 - Practicing

• "When performance matters, professionals practice."

• "Practicing is what you do when you aren't getting paid. You do it so that you will be paid, and paid well."

Chapter 7 - Acceptance Testing

Communicating Requirements

• "In reality, the communication of requirements is extremely difficult, and the process is fraught with error."

• "...customers actually discover what they need. I learned that their vision of the features does not often survive actual contact with the computer."

Premature Precision

• "Both business and programmers are tempted to fall in to the trap of premature precision. Business people want to know exactly what they are going to get before they authorize the project. Business people want to know exactly what they are supposed to deliver before they estimate the project. Both sides want a precision that simply cannot be achieved, and are often willing to waste a fortune trying to attain it."

The Uncertainty Principle

• "The problem is that things appear different on paper then they do in a working system. ... Once they (the business) they see the requirement actually running, they have a a better idea of what they really want - and it's usually not what they are seeing."

Estimation Anxiety

• "Professional developers understand that estimates can, and should, be made based on low precision requirements, and recognize that those estimates are estimates."

Late Ambiguity

• "It is the reponsibility of professional developers (and stakeholders) to make sure that all ambiguity is removed from the requirements."

Acceptance Tests

• "...acceptance tests as tests written by collaboration of the stakeholders and the programmers in order to define when requirement is done."

The Definition of "Done"

• "Professional developers have a single definition of done: Done means done. Done means all code written, all tests pass, QA and the stakeholders have accepted. Done."

Communication

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

Automation

• "Acceptance tests should always be automated. There is a place for manual testing elsewhere in the software lifecycle, but these kinds of tests should never be manual. The reason is simple: cost."

• The following quote is apropos the story of the company that had manual test plans which it executed once every six weeks... "The cost of running the manual test plan is so enormous that they have decided to sacrifice it and simply live with the fact that they won't know if half of their products works!"

Extra Work

• "Specifying at this level of detail is the only way that the stakeholders can ensure that the system they are paying for really does what they need."

Acceptance Tests and Unit Tests

• "Their primary purpose is to formally document the design, structure, and behaior of the system. The fact that they automatically verify the design, structure, and behavior that they specify is wildly useful but the specification is their true purpose."

GUIs and Other Complications

• "...you can treat GUI as though it were an API..."

• "The layout, format, and workflow of the GUI will change for easthetic and efficiency reasons, but the underlying capability of the GUI will remain the same despite these changes."

Continuous Integration

• "It is important to keep the CI tests running at all times. They should never fail. If they fail, then the whole team should stop what they are doing and focus on getting the broken test to pass again."

Conclusion

• "Communication about details is hard."