Clean Code

Company on-site, June 2022
Steve Olsen

Ruh Roh!

who would????

"Cowboy" developer:

Lazy

No rules

No team

No time

Get 'er done!
Pew pew pew!

Quotes:

  • I do my testin' in production!
  • Bugs are my job security.
  • When I wrote this code, only God and I understood what it did. Now only God knows!
  • Copy-and-paste was programmed by programmers for programmers, actually.

"

"

Resources

# mystery

of the cowboy code calamity

Private Eyes

  • Review each person's code sample
  • Identify the villain to lock-em-up
  • The world is counting on you!

Person 1

Person 2

Person 3

Are you up to the challenge?

# live code review

App: "Funnierz JOKES"

CodeSandbox link

Let's Review

  • Person 1
  • Person 2
  • Person 3
  • Patterns

Files

  • More files = smaller files, less code ✅
  • Less files = bigger files, more code ❌
  • File names = descriptive responsibility ✅
  • Parent folder = DRY file namespace ✅

Comments

  • Bad code? Then clean it, don't comment it! ✅
  • Seen as a failure to express yourself
    • (and you will fail sometimes)
    • consider it as a last resort, not Plan A
  • Some comments are GREAT ✅
    • big perspective / non-local code
    • explain past failures, do not repeat
    • "here-be-dragons" / warnings
    • TODOs -- minimal, specific context/plan
  • Comments can: lie, rot, insult, clutter, pack-rat ❌

Naming Things (is hard!)

  • code things

    • (verbs, nouns, prefixes, positive bools, etc.)

    • eg. *.component.tsx == redundant info!

      eg. const user; const userData; const userDetails

      eg. onX; handleX; enableX; setX; getX; findX;
      eg. hasX; isX      ; isNotX; filteredX; rawX; scrubbedX;

  • filesystem things

    • (files, directories)

    • parent namespaces are assumed by children

    • kabab or camelcase -- pick one

  • vocab -- pick one name per concept / entity

Functions

Q: How many lines (or statement) should a function have?

Functions

  • concise, short -- 10 statements or less
    • easily understandable
    • easily testable
    • less rope to hang yourself with
  • polite vs. rude
    • early exits -- allow "skimming"
    • same level of abstraction -- high vs. low
  • learn popular functional patterns and terms
  • lots more .... TBA 🙍‍♂️

Testing

  • Living documentation; increase confidence ✅
  • Several layers deep of "helper" abstraction ❌
  • Isolated; single-purpose; descriptive ✅
import type { Options } from "./types"
import target from "./text-manipulation"
// function signature: (jokes: string[], opts: Options)

describe("text-manipulation", () => {
  let fixture: string[]
  let opts: Options

  beforeEach(() => {
    fixture = ["Hi there.", "THIS IS NOT a drill!"]
    opts = {}
  })

  it("should add exclamations", () => {})

  it("should add lols", () => {})

  it("should make all caps", () => {})
})

# justice

is served

Formula:

  1. Desire

  2. Refactor

  3. Peer Review

  4. Practice

Code Quality Kite

OPTIMIZED (<5%)

MAINTAINABLE (>90%)

WORKING (<5%)

refactor, test

heavy test

More Pro Tips:

  1. minimize if-nesting-hell
  2. prefer maps (over if's) for condition logic
  3. use array iterator looping funcs, when possible
  4. function arg count of 0-3, or a dictionary
  5. functions should fit on one screen, no scrolling
  6. functions shouldn't mutate their args data
  7. "DRY" — function extractions and sharing
  8. avoid useless "DRY"!
  9. magic values should be assigned to variables
  10. “gnitpick” PR comments are valuable!
    • share a reason, be open to change of mind

(5 minute examples, skip over)

Deep Thoughts:

  • If debugging is the process of removing bugs, then programming must be the process of putting them in.
  • No code has zero defects. (double meaning)
  • Deleted code is debugged code.
  • Always write your code as if the person who ends up maintaining your code will be a violent psychopath who knows where you live.

"

"

Clean Code--Worth it?!?

  • software:
    • needs to change over time - maximize flexibility
    • needs teams to change it at a fast enough pace - maximize understandability
  • software:
    • is an art (interpreted by humans)
    • is a science (interpreted by logic)
    • written for humans to read, not computers to run
    • if it doesn’t make sense to developers, then it's wrong
  • PR code reviews should expose this problem
  • Simple, not easy

When is code
"good enough"?

  • When the code is self-describing (intuitive)
  • When the code follows convention (single-author)
  • When potential changes are possible (anti-brittle)
  • When further changes are trivial (refactored)
  • When known scenarios are tested (robust)

Two types of devs;

Can't    vs.    Won't

Don't be that cowboy!

Improve at your craft.

You'll feel much better

# Action items

List of Suggestions:

  • Don't rubber-stamp PR code reviews; invest
  • Next sprint retro
  • Lunch-and-learn
  • Working Group
    • Project code conventions
    • PR code reviews
    • Testing best practices
    • etc.
  • Contact your manager/Jeff King/me!

# THANK YOU

Questions?

"Clean code has
big benefits, but it needs: education, discipline, and enforcement."

Don't settle; make it clean.

Made with Slides.com