Tag Archives: read-code

[uberconf 2023] making sense of other people’s code

Posted on by
Reply

Speaker: Scott Wierschem

@scott_wierschem

For more, see the table of contents

General

  • “I’m not a great programmer.. I’m a good programmer with great habits” – Kent Beck
  • 90% of time reading code (vs writing) – Robert C Martin from Clean Code
  • 58% time understanding code – IEEE
  • Content vs intent

Reading Prose vs Code

  • Prose is passive, remember general details, constant forward flow, relaxing and enjoyable
  • Code is active reading, understand everything in detail, loops/jumps/subroutines/async, exhausting hard word

Why code hard to read

  • Variable names
  • Long methods
  • Variable state
  • Complicated control flow
  • Long files
  • Someone else wrote it
  • I wrote it, bus must have been drunk
  • No docs or old/wrong docs
  • Not following code standards
  • Magic numbers
  • Reused variables (ex: second purpose in method)
  • Global variables/singletons
  • Bad naming
  • Magical annotations
  • Using new feature in language before understanding where fits

Why read code?

  • Learn how it works to enhance or fix
  • Learn how library/framework works
  • Learn different programming techniques – learn from other people
  • Code review – paid to read it

Learning

  • Book recommendation: The Programmer’s Brain
  • FIlter info and put in short term memory – 3-5 items; only lasts about 30 seconds
  • Associated info with something and then in long term memory
  • Load from short and long term memory into working memory
  • Working memory typically 2-4 items

Confusion when reading code

  • Lack of knowledge – ex: APL (a programming language) – Greek symbols
  • Lack of information – ex: not knowing what a lambda does
  • Lack of processing power – ex: too much complexity

Example

  • Flashed characters for a second or two.
  • Cyrlic. Remembered one character
  • Random letters. Remembered three characters. Characters in long term memory.
  • Three words. Remembered all three. Words in long term memory. Chunking – grouping together familiar patterns.

Iconic memory

  • Persistence of vision
  • Look at shape of code ex: of statement
  • Can see indents even in minimap where code is tiny (CodeGlance Pro plugin for IntelliJ; Eclipse/VS Code have setting)

Other guides/tools

  • Design patterns for chunking
  • Comments – new people rely on a lot more. Experienced people burned by docs and learn to remove.
  • Print code and write on it as external aid
  • Create dependency graph – print out/highlight or use a tool – https://annotate.codereading.club/
  • Use a state table – write down values of variables as go thru code/loops

Beacons

  • Simple Beacon – good variable name
  • Compound Beacon – combinations
  • Help future readers of code
  • Intentionally included to make easier to read/understand
  • Whitespaced for sections of code
  • Eye drawn automatically to bits of code

Remembering stuff

  • Faster to make associations when know more
  • Faster to learn
  • Break flow to google.
  • Takes average 15 minutes to get back to where you were
  • Remember through repetition; memory decays. The decay is slower over time. This is why spaced repetition works. ankiapp.com, cerego.com, quizlet.com)
  • Long term memory is good. Retrieval doesn’t always work. Practice helps. Try to guess before look it up.

Cognitive Load

  • Intrinsic – complexity of problem
  • Extraneous – outside distractions
  • Germane – storing thought in long term memory
  • Reduce load by refactoring – break it up, remove duplication, simplify, sometimes unroll function call, avoid unfamiliar language constructs (ex: ternary operator)
  • Can have IDE refactor for you without understanding first
  • Add confusing constructs to flash cards so can make association faster next time

Similarities

  • Write down what concept makes you think of; what is related
  • For each concept, think about why related. ex: syntax, context
  • What other ways can accomplish same goal? ex: other programming languages
  • Does it fit a paradigm, domain, library, framework, etc

Tools

  • IDE plugins – syntax coloring, indentation lines, plugins. Know your IDE; know the features
  • Paper and pen – colored pens/pencils, highlighters
  • Debugger – conditional breakpoints [these are great]
  • Profiler – call stacks
  • Log files

My take

I’m a morning person, so I wasn’t sure how live blogging at a talk at 8:30pm would go. It was right after dinner though so that helped me stay alert. It helped that he had a lot of interactivity. I still had trouble concentrating as much as I could earlier in the day though so I’m sure I retained less. Good thing I have this blog post. I will say brain being worn out was very reinforcing when finding code with higher cognitive load!