AdobeXD brought in Robert Martin to teach a Clean Code Course over the next few days. Decided to post my notes as we are going along. I’ll keep posting my notes as we go along. Updated: day 2, Refactoring; day 3, Unit Tests.
Comic: The only valid measurement of code quality: WTFs/minute
There will be code.
A fragile premise?
“Good code matters.” –Kent Beck
Everybody gets slowed down by bad code – why do we write it?
We confuse the need for speed with the need for clean code.
Metaphor – What’s the fastest way to be done with dinner? Get up from the table and not do the clean up. When it is time to eat we just find the cleanest dishes and when dinner is over we leave the dishes dirty again. Eventually it is so hard to make dinner we outsource dinner. Sushi chefs clean as they prepare food. If you want to go fast – go as clean as you can. The only way to go fast is to go clean.
We can blame a lot of things for leaving a mess behind. Ultimately we are the ones who make the mess.
Excuses:
The deadline looms.
The backlog grows.
Managers are testy.
When managers approach and ask you to go faster we need to hold the line. Make sure they understand that the best way to go faster is to code cleaner.
Metaphor – The doctor and the patient. The doctor is the servant and the patient is the customer. Even still the doctor is the boss. The patient needs to relinquish a certain amount of control to the doctor to allow them to be the most efficient.
We are paid because we are the experts.
This is the dilemma that we as developers face and we haven’t been doing a very good job.
“Later equals never”
Productivity vs Time
On a new project the beginning of the project we are the most efficient and get the most done. It doesn’t last. Over time the code becomes more complex and productivity goes down.
The mess grows so big and so deep and so tall, they can not clean it up. There is no way at all.
When productivity goes down the business hires more people. Productivity goes down during training; it might go back down. Then the business decides to redesign. They pick the 10 best and start a tiger team to head up the redesign. Then there is a race with the rest of developers maintaining the code.
Xeno’s paradox
Boy Scout rule – always leave the code cleaner than you found it, and do some random act of kindness.
Why does code rot?
When we find dirty code, we don’t want to touch it because if something breaks the code will be assigned to us to fix it.
If you want to be able to clean code – you need to have a suite of tests that you trust.
You only trust tests you write first.
– Break –
The planets take odd paths as they travel across the sky. They actually back track.
What color does you IDE make your comments? Green, why? It is calming – sometimes it’s faded so as to not distract. Meaning the comments are less important.
Comments rot when we don’t pay attention to them. Eventually comments become lies and things change and they do not. We should have a reason for every line of code we write, even/especially comments.
Refrain from adding comments in your code that contains information contained elsewhere, including the source control system.
Instead of including HTML formatting in the comments (for source docs) use only the pre tag (as a concession for the docs)
DW: Comments are sometimes written for the developer to think through what they are building.
UncleBob: So they are masturbatory?
Your effort is to make your code as readable as possible.
Writing code should follow the journalism rule – order the contents of your class in order of importance.
Maybe the private symbol doesn’t belong in an abstract class at all.
It isn’t just nice to have an IDE that will support refactoring, it is necessary.
Sometimes conventions are more important than common sense. The principle of common surprise.
Never make your users do a double take.
The best documentation for a module is the source code for the module. The code should be written in the most readable fashion with a smattering of helpful comments.
We have the impression that frequent comments means we are a good developer.
You should look at every comment as a failure. We still write comments because we still have failures.
Here is the issue, we are the developers, the code is our document. We have stupid rules put on us because we have behaved unprofessionally in the past. We have to suffer through it now.
– Break –
Long Functions
Avoid nested if statements
Avoid large dynamic ranges within functions
First Rule of Functions
They should be small
Second Rule of Functions
They should be smaller than that.
Function should not be 100 lines long.
Functions should hardly ever be 20 lines long.
Smallness implies that blocks within:
if
else
while
etc
should be one line long.
Probably that line should be a function call.
Smallness also implies:
functions should not be large enough to hold nested structures
therefore the indent of level of a function should not be greater than one or two
this makes the functions easy to read and understand
A large function usually hides one or more classes.
A function is cohesive if it does one thing, does it well, and does it only
Extract until you drop
“I like my code to be elegant and efficient… clean code does one thing well.”
– Bjarne Stroustrup
“Clean code is simple and direct. Clean code reads like well-written prose…”
– Grady Booch
“Clean code can be read… Clean code should be literate…”
– “Big” Dave Thomas
“Clean code always looks like it was written by someone who cares”
–Michael Feathers
“You know you are working on clean code when each routine you read turns out to be pretty much what you expected…”
– Ward Cunningham
– Day 2 –
Refactoring
You can write something badly and then manipulate it.
(Uncle Bob’s personal rule) Don’t ever make the developer scroll right (in the IDE).
Never test through the UI. (Don’t test business rules through the GUI).
Rule for writing tests – Intentional Coding! Write the tests for the code you wish you had.
First refactor the tests. Make sure they are easy to maintain or you’ll eventually throw them out.
The tests are the parachute you are going to jump out of plane with; make sure they are folded correctly.
As far as performance – you don’t know where the bottle neck is until you profile. You can look at the code and refactor all day without improving performance unless you first check to see where the problem is.
– Break –
Switch/If statements can be refactored into polymorphic dispatcher.
Uncle Bob’s Three Laws
1) Write NO production code except to pass a failing test.
2) Write only enough of a test to demonstrate a failure.
3) Write only enough production code to pass the test.
Unless you’ve tried it, you should find these rules to be rediculous.
Book – Working Effectively with Legacy Code by Michael Feathers
As tests become more specific, production code must become more generic.
http://cleancoder.posterous.com/the-transformation-priority-premise
– Day 3 –
No more than three arguments in a function.
Don’t use booleans as arguments.
Avoid output arguments.
