Exercise: Other People's Code

James Lyndsay -

Consider your own code through the lens of other people's code.

Purpose: to reveal how to we might make our code more open to other people.

Method: Read other people’s code. Identify what might make parts of that code easy or difficult to understand. Decide what you might adjust in your  own code.

Logistics: 40-60 minutes, working group 2-10.

Sequence

  1. Pick your language / tech stack / area of interest

2. Find some unfamiliar code which someone else has written. You might:

  • Search in GitHub
  • Look on Rosetta Code
  • Pick up some code from elsewhere in your organisation

3. Spend 10 minutes reading the code and any surrounding text. Confusion is your marker – keep track of the points where you’re wondering, whether you resolve it or not.

Try to understand (several or all of): its structure / its purpose / what it parameterises and returns / what keywords it uses / how it has named its data and functions / how it gets around tech stack weirdnesses.

4. Come back to the group with one or more of the following

  • An example of something that you (initially?) struggled to understand, and (if you can) the changes / comments / context needed to reduce that struggle
  • If you understand it all, then an example of something that you would do differently, what you would do, and why you prefer your way

5. The group will pick a few.

6. Using those examples, consider what you might do to make any code you work on to be more-easily understandable.