Peter Hilton - Speaking & training

How to write maintainable code

Naming and tests versus comments and documentation

Modern languages’ biggest problem isn’t having enough cool features, it’s unmaintainable code. The core of maintainable code is clean code with good tests, but that by itself is not enough. This talk introduces a range of techniques for writing and improving code for maintainability, including how to get better at naming, explaining code with tests, the few code comments you actually need, README-driven development and how to write Minimum Viable Documentation.

Attendees will see how to combine a number of techniques they have already encountered separately, plus at least one technique they’ve never heard of and can use immediately. Naming and abstraction are too hard to get right every single time, so you need to know when to add small doses of comments and documentation. More importantly, you need to know how to avoid wasting time on bad comments and unnecessary documentation without giving up entirely and not having any at all.

After the excitement of early adoption, and the joy of coding among experts comes the horror of your first maintenance project. As Jean-Paul Sartre said*, ‘Hell is other people’s code’. Whether you are a new developer or an experienced team lead, your future developer experience and happiness depends on maintainable code.


How to write maintainable Scala code video at



Share on TwitterShare on LinkedIn