Slideshare uses cookies to improve functionality and performance, and to provide you with relevant advertising. If you continue browsing the site, you agree to the use of cookies on this website. See our User Agreement and Privacy Policy.

Slideshare uses cookies to improve functionality and performance, and to provide you with relevant advertising. If you continue browsing the site, you agree to the use of cookies on this website. See our Privacy Policy and User Agreement for details.

How to write maintainable code

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 Scala developer or an experienced team lead, your future developer experience and happiness depends on maintainable code.

7.
Consequences of unmaintainable code
1. Higher cost to develop a new feature or fix a bug
2. Developers become unhappy and leave
3. Higher cost to hire new developers
4. Fewer good developers on the team
5. Code gets less maintainable
6. Go back to step 1 - enjoy the descent into legacy code hell
9@PeterHilton •

11.
Use a consistent coding style
Pick one way to use/avoid FP and OOP, and stick to it.
This is easy, provided that you never:
1. learn anything new about your language
2. learn anything new about functional programming
3. learn anything new about programming
4. move to a newer language version
5. work with other people who have diﬀerent backgrounds
13@PeterHilton •

12.
@PeterHilton •
Learning to write clean code
is the first step towards
maintainable code
There’s a book for that!
However, the book isn’t
perfect and doesn’t target
Scala.
15

13.
Naming things
16@PeterHilton •
Good names for everything are the key to clean code
How hard can it be?*
Use software tools, practice, get better at it.
* see me afterwards if you don’t know any jokes about
naming things being hard

20.
@PeterHilton • 24
‘Like cheap wine, long paper
documentation ages rapidly
and leaves you with a bad
headache if you try to use it
a year after it was created.
On the other hand,
maintaining a system
without any documentation
also causes headaches.’

23.
Clean code and good
unit tests are great,
but they’re not enough
(this is the bad news)
27@PeterHilton •

24.
Clean code & tests are not enough
Even if you could write clean code all the time (you can’t)
your code still needs more explanation.
You don’t have to repeat yourself to the compiler, but
human learning requires repetition.
You have to repeat yourself to help people understand you.
However, Uncle Bob is misleading about comments…
28@PeterHilton •

25.
Comments are the
easiest way to document
code. If you don’t have
comments, you probably
have no docs at all. 29@PeterHilton •

28.
@PeterHilton •
Avoiding duplication
at all costs may lead
to incomprehensible
abstractions.
32

29.
Too much abstraction
Dogmatic adherence to do-not-repeat-yourself leads to too
many abstractions.
Most of these abstraction layers don’t correspond to the
domain, so you can’t find good names for them.
(Half probably aren’t abstractions anyway, just indirection)
33@PeterHilton •

30.
The Rule of Three
‘The first time you do something, you just do it.
The second time you do something similar, you wince at the
duplication, but you do the duplicate thing anyway.
The third time you do something similar, you refactor.’
- Kevlin Henney
https://vimeo.com/138863968
34@PeterHilton •

31.
35@PeterHilton •
6. Apply The Rule of Three
before you remove
duplication

36.
Clean code
All of your code can be clean code, in theory…
But this gets harder as the codebase grows
Code falls oﬀ the maintenance cliﬀ after around 100K lines
This is more likely to happen with business applications
than focused libraries for developers
(Likely the strongest argument for external dependencies)
40@PeterHilton •

39.
Constantly improve the code
Take the Boy Scout Principle seriously (actually enforce it)
Do code review on all changes
Recognise code smells
Refactor
Even if you can’t win, you can lose more slowly
43@PeterHilton •

41.
README-Driven Development
45@PeterHilton •
‘… we have projects with short, badly written, or entirely
missing documentation…
There must be some middle ground between reams of
technical specifications and no specifications at all. And in
fact there is.
That middle ground is the humble Readme.’
http://tom.preston-werner.com/2010/08/23/readme-driven-development.html

42.
Write a project/project introduction
Explain the system’s purpose
(What is the business reason? Why are we here?)
Describe the scope
(What defines what the system does and doesn’t do?)
Summarise what it does
(What does it actually do? What is it for?)
46@PeterHilton •