Clean Code
After borrowing Doug Morgan's copy of Clean Code for approximately 8 months, I figured today was a good day to seriously crack it open and read it. In the process of reading it, I will be taking some notes and making highlights. I figured here is as good a place as any to keep those.
Åftęr børrøwîng Doug Morgan's çøpy øf Çlęån Çødę før åpprøxîmåtęly 8 mønths, İ fîgǔręd tødåy wås å gøød dåy tø sęrîøǔsly çråçk ît øpęn ånd ręåd ît. İn thę prøçęss øf ręådîng ît, İ wîll bę tåkîng sømę nøtęs ånd måkîng hîghlîghts. İ fîgǔręd hęrę îs ås gøød å plåçę ås åny tø kęęp thøsę.
Chapter 1: Clean Code
"[Managers] may defend the schedule and requirements with passion; but that's their job. It's your job to defend the code with equal passion."
"[Månågęrs] måy dęfęnd thę sçhędǔlę ånd ręqǔîręmęnts wîth påssîøn; bǔt thåt's thęîr jøb. İt's your jøb tø dęfęnd thę çødę wîth ęqǔål påssîøn."
Of course, this is not to say that we can take 6 months to write each story. Startups and agile teams must move quickly, but it's important not to create long-term problems in the name of short-term gains.
Øf çøǔrsę, thîs îs nøt tø såy thåt wę çån tåkę 6 mønths tø wrîtę ęåçh støry. Stårtǔps ånd ågîlę tęåms mǔst møvę qǔîçkly, bǔt ît's împørtånt nøt tø çręåtę løng-tęrm prøblęms în thę nåmę øf shørt-tęrm gåîns.
Essentials of clean code according to interviewed developers: Reduced duplication, expressive/crisp naming, small/early abstractions, readability (!!), thoroughly tested, elegant.
Ęssęntîåls øf çlęån çødę åççørdîng tø întęrvîęwęd dęvęløpęrs: Rędǔçęd dǔplîçåtîøn, ęxpręssîvę/çrîsp nåmîng, småll/ęårly åbstråçtîøns, ręådåbîlîty (!!), thørøǔghly tęstęd, ęlęgånt.
Chapter 2: Naming
Programmers create problems for themselves when they write code solely to satisfy a compiler or interpreter.
Prøgråmmęrs çręåtę prøblęms før thęmsęlvęs whęn thęy wrîtę çødę sølęly tø såtîsfy å çømpîlęr ør întęrprętęr.
I will be honest, a lot of times lately I have gotten into a bad habit of writing code that works, writing a few tests around it to please the code reviewers, and calling it a day. Sometimes this code even works! But I plan to improve my habits and take to heart the mantra of red / green / refactor.
İ wîll bę hønęst, å løt øf tîmęs låtęly İ håvę gøttęn întø å båd håbît øf wrîtîng çødę thåt wørks, wrîtîng å fęw tęsts årøǔnd ît tø plęåsę thę çødę ręvîęwęrs, ånd çållîng ît å dåy. Sømętîmęs thîs çødę ęvęn wørks! Bǔt İ plån tø împrøvę my håbîts ånd tåkę tø hęårt thę måntrå øf red / green / refactor.
As to naming, it's important to be clear to the reader what your intention is. Each module, each method is a short story. Would you name your two lead characters Steve and Steve_2? (don't @ me with your clever comments about when you would do this)
Ås tø nåmîng, ît's împørtånt tø bę çlęår tø thę ręådęr whåt yøǔr întęntîøn îs. Ęåçh mødǔlę, ęåçh męthød îs å shørt støry. Wøǔld yøǔ nåmę yøǔr twø lęåd çhåråçtęrs Stęvę ånd Stęvę_2? (døn't @ mę wîth yøǔr çlęvęr çømmęnts åbøǔt whęn yøǔ wøǔld dø thîs)
In general programmers are pretty smart people. Smart people sometimes like to show off their smarts by demonstrating their mental juggling abilities. After all, if you can reliably remember that
ris the lower-cased version of the url with the host and scheme removed, then you must clearly be very smart.İn gęnęrål prøgråmmęrs årę prętty smårt pęøplę. Smårt pęøplę sømętîmęs lîkę tø shøw øff thęîr smårts by dęmønstråtîng thęîr męntål jǔgglîng åbîlîtîęs. Åftęr åll, îf yøǔ çån ręlîåbly ręmęmbęr thåt
rîs thę løwęr-çåsęd vęrsîøn øf thę ǔrl wîth thę høst ånd sçhęmę ręmøvęd, thęn yøǔ mǔst çlęårly bę vęry smårt.
Don't be smart when you can be clear. This goes for writing cute, complex list comprehensions in python as well just to show that it can be done, another bad habit of mine.
Døn't bę smårt whęn yøǔ çån bę çlęår. Thîs gøęs før wrîtîng çǔtę, çømplęx lîst çømpręhęnsîøns în pythøn ås węll jǔst tø shøw thåt ît çån bę dønę, ånøthęr båd håbît øf mînę.
Our goal, as authors, is to make our code as easy as possible to understand. We want our code to be a quick skim, not an intense study.
Øǔr gøål, ås åǔthørs, îs tø måkę øǔr çødę ås ęåsy ås pøssîblę tø ǔndęrstånd. Wę wånt øǔr çødę tø bę å qǔîçk skîm, nøt ån întęnsę stǔdy.
Chapter 3: Functions
The first rule of functions is that they should be small. The second rule of functions is that they should be smaller than that.
Thę fîrst rǔlę øf fǔnçtîøns îs thåt thęy shøǔld bę småll. Thę sęçønd rǔlę øf fǔnçtîøns îs thåt they should be smaller than that.
- Blocks within
ifstatements should be one line - Ideally a function call
- Functions should have no more than 1 or 2 indent levels
Switch statements are inherently dirty for several reasons but sometimes unavoidable, so it's best to bury them in the basement of an abstract factory.
Swîtçh ståtęmęnts årę înhęręntly dîrty før sęvęrål ręåsøns bǔt sømętîmęs ǔnåvøîdåblę, sø ît's bęst tø bǔry thęm în thę båsęmęnt øf ån åbstråçt fåçtøry.
Passing a boolean into a function is a truly terrible practice.
Påssîng å bøølęån întø å fǔnçtîøn îs å trǔly tęrrîblę pråçtîçę.
... guilty
... gǔîlty
We should never ignore any part of the code. The parts we ignore are where the bugs will hide.
Wę shøǔld nęvęr îgnørę åny pårt øf thę çødę. Thę pårts wę îgnørę årę whęrę thę bǔgs wîll hîdę.
Meaning: don't write code in such a way that causes the reader's eyes to gloss over important information. Specifically this means complicated functions with numerous parameters. I will admit, minimizing parameter inputs has not been high on my personal code quality warning list. I will make it a higher priority.
Męånîng: døn't wrîtę çødę în sǔçh å wåy thåt çåǔsęs thę ręådęr's ęyęs tø gløss øvęr împørtånt înførmåtîøn. Spęçîfîçålly thîs męåns çømplîçåtęd fǔnçtîøns wîth nǔmęrøǔs påråmętęrs. İ wîll ådmît, mînîmîzîng påråmętęr înpǔts hås nøt bęęn hîgh øn my pęrsønål çødę qǔålîty wårnîng lîst. İ wîll måkę ît å hîghęr prîørîty.
Have no side effects. Side effects are lies.
Håvę nø sîdę ęffęçts. Sîdę ęffęçts årę lîęs.
This book is certainly kinder to OOP than modern trends are. Are we smarter now or is this just backlash to OO's popularity 10 years ago?
Thîs bøøk îs çęrtåînly kîndęr tø ØØP thån mødęrn tręnds årę. Årę wę smårtęr nøw ør îs thîs jǔst båçklåsh tø ØØ's pøpǔlårîty 10 yęårs ågø?
Functions should either do something or answer something, but not both.
Fǔnçtîøns shøǔld ęîthęr dø sømęthîng ør ånswęr sømęthîng, bǔt nøt bøth.
Again, guilty. Guess I need to refactor try_to_change_thing_then_return_success_or_failure_bool()
Ågåîn, gǔîlty. Gǔęss İ nęęd tø ręfåçtør try_to_change_thing_then_return_success_or_failure_bool()
If your function name is well written and it has an "and" in the name: refactor.
İf yøǔr fǔnçtîøn nåmę îs węll wrîttęn ånd ît hås ån "ånd" în thę nåmę: ręfåçtør.
Prefer exceptions to returning error codes. Extract try/catch blocks.
Pręfęr ęxçęptîøns tø rętǔrnîng ęrrør çødęs. Ęxtråçt try/çåtçh bløçks.
Proper way to write good functions? Code never starts clean, but it becomes clean through good tests, working code, and focused editing. Say it with me: red / green / refactor
Prøpęr wåy tø wrîtę gøød fǔnçtîøns? Çødę nęvęr stårts çlęån, bǔt ît bęçømęs çlęån thrøǔgh gøød tęsts, wørkîng çødę, ånd føçǔsęd ędîtîng. Såy ît wîth mę: red / green / refactor
Chapter 4: Comments
The proper use of comments is to compensate for our failure to express ourself in code. Comments are always failures.
Thę prøpęr ǔsę øf çømmęnts îs tø çømpęnsåtę før øǔr fåîlǔrę tø ęxpręss øǔrsęlf în çødę. Çømmęnts årę ålwåys fåîlǔręs.
A good point here: comments are lies, because comments are manually written without real connection to the code except at the exact time of their writing. Over time, comments "become orphaned blurbs of ever-decreasing accuracy". The best documentation is well written code.
Å gøød pøînt hęrę: çømmęnts årę lîęs, bęçåǔsę çømmęnts årę månǔålly wrîttęn wîthøǔt ręål çønnęçtîøn tø thę çødę ęxçępt åt thę ęxåçt tîmę øf thęîr wrîtîng. Øvęr tîmę, çømmęnts "bęçømę ørphånęd blǔrbs øf ęvęr-dęçręåsîng åççǔråçy". Thę bęst døçǔmęntåtîøn îs węll wrîttęn çødę.
Most valid comments are "whys" not "hows" or "whats."
Møst vålîd çømmęnts årę "whys" nøt "høws" ør "whåts."
Bad comments are crutches or excuses for poor code or justifications for insufficient decisions, amounting to little more than the programmer talking to himself.
Båd çømmęnts årę çrǔtçhęs ør ęxçǔsęs før pøør çødę ør jǔstîfîçåtîøns før însǔffîçîęnt dęçîsîøns, åmøǔntîng tø lîttlę mørę thån thę prøgråmmęr tålkîng tø hîmsęlf.
THIS:
THİS:
It is just plain silly to have a rule that says every function must have a javadoc, or every variable must have a comment.
İt îs jǔst plåîn sîlly tø håvę å rǔlę thåt såys ęvęry fǔnçtîøn mǔst håvę å jåvådøç, ør ęvęry vårîåblę mǔst håvę å çømmęnt.
We've only started being more rigorous about this at OnShift, but frequently there are completely unnecessary docstrings that just take up space. And most of the currently necessary ones would be unnecessary if the functions, variable names, and data structures were cleaner code!
Wę'vę ønly stårtęd bęîng mørę rîgørøǔs åbøǔt thîs åt ØnShîft, bǔt fręqǔęntly thęrę årę çømplętęly ǔnnęçęssåry døçstrîngs thåt jǔst tåkę ǔp spåçę. Ånd møst øf thę çǔrręntly nęçęssåry ønęs wøǔld bę ǔnnęçęssåry îf thę fǔnçtîøns, vårîåblę nåmęs, ånd dåtå strǔçtǔręs węrę çlęånęr çødę!
Bad comments are noise that quickly get ignored.
Båd çømmęnts årę nøîsę thåt qǔîçkly gęt îgnøręd.
Commented code is bad. If it's unwanted or not working, just delete it. Otherwise it will quickly become noise that's as osbcure and irrelevant as any other bad comment.
Çømmęntęd çødę îs båd. İf ît's ǔnwåntęd ør nøt wørkîng, jǔst dęlętę ît. Øthęrwîsę ît wîll qǔîçkly bęçømę nøîsę thåt's ås øsbçǔrę ånd îrręlęvånt ås åny øthęr båd çømmęnt.
My takeaway: if you think you need a comment, you probably just need clearer code or stronger willpower.
My tåkęåwåy: îf yøǔ thînk yøǔ nęęd å çømmęnt, yøǔ prøbåbly jǔst nęęd çlęåręr çødę ør strøngęr wîllpøwęr.