canspice.org

The full title of this talk is “Skimmable Code: Fast to Read, Safe to Change”, and it’s presented by Michael Schwern.

What does Schwern mean by “skimmable”? He means in terms of like skimming a book — you skim through the book to find info you want, rather than studying the entire thing, because you want to find the info fast.

Why skim? It allows you to focus on a single task. It lets you slice through hairy code. It lets you free up brainpower. This talk is essentially applied best practices, it explains the reasoning behind best practices.

How do you skim? It all comes down to narrowing your focus. How do you do that? Your primary weapon is “lexical encapsulation” — look at the stuff that’s right in front of your face. Not the subroutine calls, not method calls, just the stuff between the braces (that’s in your lexical scope).

Tests are useful for making code skimmable, because at the touch of a button you can see if your modifications have broken anything. When refactoring code, refactor, then test, then commit, then repeat. If you fail a test, you can find out where you’ve broken things (and always test before committing).

Rename refactoring: use good names. For example, calling something $arg isn’t useful; call it something that describes what it is actually used for. This way you don’t have to keep referring back up to the top to figure out what the argument is.

Extract refactoring: extract routines and methods out to prevent other routines from doing too much that you can’t keep it all in your head. After you extract routines out to subroutines, it cleans up the structure of your program and you may be able to extract more routines out to subroutines again.

Whitespace allows clarity. Vertical whitespace can be used to differentiate between major blocks in your code. Similar things should look similar, so if you’re using a hash constructor try lining up the fat commas.

Different things should be displayed differently, e.g. $lexical vs $Global.

Red flags: No documentation. No tests. Things are deeply nested. Compound names (e.g. make_waffles_and_pancakes. Generic names (e.g. @list, $arg, $data). Overly verbose (e.g. $total_amount_spent_on_food). Globals. Scope closing comments. Long routines.