How to write maintainable Scala code


Published on

Scala’s biggest problem isn’t adoption any more, 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 Scala 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.

Published in: Technology
1 Comment
No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

How to write maintainable Scala code

  1. 1. @PeterHilton How to write maintainable Scala code
  2. 2. We’ve solved the Scala adoption problem 🎉 (that was the good news) 2@PeterHilton •
  3. 3. Wikimedia / CC BY-SA 3.0
  4. 4. Writing unmaintainable code in Scala
  5. 5. Scott Edmunds / CC BY 2.0 Scala gives you all the toys
  6. 6. Scala’s maintainable code problem 1. OOP and FP at the same time 2. Exceptionally expressive programming language 3. Relatively rapid language development 4. Early-adopter culture 5. Computer science vs mathematics vs enterprise dev 7@PeterHilton •
  7. 7. Split development community California school (Java programmers) Want straightforward code
 Mix Java-style OOP with functional programming
 Prefer domain modelling to functional abstractions
 Glasgow school (mathematicians) Haskell… but in Scala 8@PeterHilton •
  8. 8. Causes of unmaintainable code We’re lazy. We’re too clever for our own good. (Scala developers especially) We should stop starting things and start finishing things (especially refactoring) 10@PeterHilton •
  9. 9. 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 11@PeterHilton •
  10. 10. Clean code & tests 
 to the rescue
  11. 11. 13@PeterHilton • 1. Learn how to write unmaintainable code* 2. Don’t do that! * How To Write Unmaintainable Code,
 Roedy Green, Canadian Mind Products
  12. 12. Marks of unmaintainable Scala code 1. Inconsistent code styles (OOP vs FP, Java vs Haskell) 2. Repetition 3. Too much abstraction (unnameable invented concepts) 4. Spaghetti code 5. Lasagne architecture (too many layers) 6. Inadequate tests (low coverage, incomprehensible) 14@PeterHilton •
  13. 13. 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 Scala 2. learn anything new about functional programming 3. learn anything new about programming 4. move to a newer Scala version 5. work with other people who have different backgrounds 15@PeterHilton •
  14. 14. @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. 16
  15. 15. Naming things 17@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
  16. 16. Piotr / CC BY 2.0
  17. 17. Naming smells 20@PeterHilton • foo, data, object employee, employee2 acc, pos, a, i, T, U >=>, <*>, ¶ InvoiceManager, getPrice isOpen, dateCreated appointment_list, company_person shipment, order, journey 1. Meaningless and abstract names 2. Numeric suffixes 3. Abbreviated or short names 4. Symbolic names 5. Vague words 6. Vestigial Hungarian notation 7. Multiple words 8. Wrong names
  18. 18. Adopting better naming practices Recognise and fix naming smells Start with meaning and intention Use words with precise meanings Prefer fewer words in names Never use abbreviations in names, except for id 21@PeterHilton •
  19. 19. How to name things
 (the hardest problem in programming) 1. Learn to recognise bad naming 2. Refactor - rename bad names to better names 3. Improve your vocabulary by reading and gaming 4. Wield your thesaurus and dictionary 5. Adopt better naming practices 6. Learn to write 7. Tell jokes, especially puns - learn to spot ambiguity 22@PeterHilton •
  20. 20. 3. Write clean code 4. Get better at naming
 23@PeterHilton •
  21. 21. Explanatory functional tests Acceptance Test-Driven Development (ATDD) Behaviour-Driven Development (BDD) Specification by Example … use acceptance tests written in domain language,
 in collaboration with requirements stakeholders, that document system behaviour (in addition to unit tests) 24@PeterHilton •
  22. 22. @PeterHilton • 25 ‘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. 23. 5. Write explanatory functional tests
 26@PeterHilton •
  24. 24. How to write 
 maintainable code
  25. 25. Clean code and good unit tests are great, but they’re not enough (this is the bad news) 28@PeterHilton •
  26. 26. 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. Unfortunately, Uncle Bob is wrong (or at least misleading) about comments… 29@PeterHilton •
  27. 27. Comments are the easiest way to document code. If you don’t have comments, you probably have no docs at all. 30@PeterHilton •
  28. 28. Write good comments 1. Try to write good code first 2. Try to write a one-sentence comment 3. Refactor the code (make it easier to explain) 4. Delete unnecessary comments 5. Rewrite bad comments
 (all good writing requires rewriting) 6. Add detail where needed
 (which isn’t often) 31@PeterHilton •
  29. 29. ‘Beware of DRY, the evil siren that tricks you into abstraction’ Martin Thompson a.k.a. @mjpt777 32@PeterHilton •
  30. 30. @PeterHilton • Avoiding duplication at all costs may lead to incomprehensible abstractions. 33
  31. 31. 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. (Half probably aren’t abstractions anyway, just indirection) 34@PeterHilton •
  32. 32. 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 35@PeterHilton •
  33. 33. 36@PeterHilton • 6. Apply The Rule of Three before you remove duplication
  34. 34. 7. Accept that maintainable code costs more 37@PeterHilton •
  35. 35. How to maintain maintainable code
  36. 36. There’s not much point writing maintainable code if you don’t actually maintain it 39@PeterHilton •
  37. 37. Proportion of clean code during software development%cleancode 0 25 50 75 100 number of lines of code April Untitled 3 Untitled 10 June Untitled 5 Untitled 8 Untitled 11 ‘We’ll clean it up later’ ‘There’s too much 
 code to clean it up’
  38. 38. Clean code All of your code can be clean code, in theory… But this gets harder as the codebase grows Code falls off the maintenance cliff 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) 41@PeterHilton •
  39. 39. v 1.58
 Language files blank comment code
 Scala 287 8035 10396 28889
 Javascript 7 3032 4729 22150
 Java 99 2066 5075 7743
 HTML 45 271 0 1286
 XML 11 16 9 151
 CoffeeScript 2 8 9 16
 SUM: 451 13428 20218 60235
  40. 40. formal continuous code review
 (pull requests) review meetings pair programming
  41. 41. 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 44@PeterHilton •
  42. 42. 8. Keep the codebase small 9. Increase refactoring effort as it grows 45@PeterHilton •
  43. 43. Manage development carefully Don’t expect to be developing features all the time Decide on the target system lifetime Practice getting new team members up to speed Work hard at keeping good people on the team Don’t expect to keep people for ever Plan to slowly rotate team members 47@PeterHilton •
  44. 44. 10.Don’t change the team Rotate team members carefully 48@PeterHilton •
  45. 45. README-Driven Development 49@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.’
  46. 46. 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?) 50@PeterHilton •
  47. 47. Detailed system documentation Most systems don’t need detailed documentation. Only complex systems require detailed documentation, e.g. Architecture diagram UML diagram Data dictionary Process model Business rules 51@PeterHilton •
  48. 48. 11.Write the minimum viable documentation
 (the rest is waste) 52@PeterHilton •
  49. 49. Summary
  50. 50. ‘Hell is other people’s code’* * Sartre didn’t actually say this 54@PeterHilton •
  51. 51. Summary 55@PeterHilton • 1. Recognise unmaintainable Scala code (and refactor) 2. Write clean code (and get better at naming) 3. Write acceptance tests that explain functionality 4. Apply The Rule of Three before you remove duplication 5. Accept that maintainable code costs more 6. Write docs and comments for the code you actually have 7. Keep the codebase small (or increase refactoring effort) 8. Avoid changing the team (and rotate carefully)
  52. 52. @PeterHilton