What I talk about when I talk about code

However good your code, other people never seem to get it. Instead they ruin your day (and your productivity) by asking questions and expecting documentation. You need to know how to explain code without being stuck in meetings or spending half your time on the only thing that’s worse than meetings: writing documentation. This presentation’s aims to fix confusion about how we really explain code to each other, and to understand programmers’ frequently irrational behaviour about the sensitive subjects of talking to each other, documentation and code comments.

This talk explores what we talk about when we talk about code, how we do it, and the tools we use. Not everyone writes detailed up-front specifications these days, but remote working and distributed teams make written explanations more valuable than ever. Talking face to face requires less effort, but you rarely or never meet the authors of most of the code you see. Software craftsmanship has failed to make written documentation unnecessary. Instead we shall turn to README-Driven Development, comments evasion, documentation-avoidance, just-in-time documentation and the art of not writing it in the first place.

Outline

• Legacy code, developer half-life & other industrial irritations
• What I talk about when I talk about code
• Ubiquitous languages, long words & other jargon
• There’s more than one way to talk about code
• Comments evasion & documentation-avoidance
• Just-in-time documentation & the art of not writing it
• README-Driven Development
• Tutorials, instructions & other written forms
• Chat rooms, wikis & other tools for talking code