Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

How to write maintainable code


Published on

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.

Published in: Technology

How to write maintainable code

  1. 1. @PeterHilton How to write 
 maintainable code
  2. 2. Wikimedia / CC BY-SA 3.0
  3. 3. Writing 
 unmaintainable code
  4. 4. Scott Edmunds / CC BY 2.0 Modern languages give you all the toys
  5. 5. Modern languages’ maintainable code problem 1. OOP and FP at the same time 2. Exceptionally expressive programming language 3. Rapid language development - major changes 4. Early-adopter culture 5. Computer science vs mathematics vs enterprise dev
 (a rich community but sometimes with conflicting goals) 6@PeterHilton •
  6. 6. Causes of unmaintainable code We’re lazy. We’re too clever for our own good. (functional programmers especially) We should stop starting things and start finishing things (especially refactoring) 8@PeterHilton •
  7. 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 •
  8. 8. Clean code & tests 
 to the rescue
  9. 9. 11@PeterHilton • 1. Learn how to write unmaintainable code* 2. Don’t do that! * How To Write Unmaintainable Code,
 Roedy Green, Canadian Mind Products
  10. 10. Marks of unmaintainable 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) 12@PeterHilton •
  11. 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 different backgrounds 13@PeterHilton •
  12. 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. 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
  14. 14. Piotr / CC BY 2.0
  15. 15. Naming smells 19@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
  16. 16. 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 20@PeterHilton •
  17. 17. 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 21@PeterHilton •
  18. 18. 3. Write clean code 4. Get better at naming
 22@PeterHilton •
  19. 19. 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) 23@PeterHilton •
  20. 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.’
  21. 21. 5. Write explanatory functional tests
 25@PeterHilton •
  22. 22. How to write 
 maintainable code
  23. 23. Clean code and good unit tests are great, but they’re not enough (this is the bad news) 27@PeterHilton •
  24. 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. 25. Comments are the easiest way to document code. If you don’t have comments, you probably have no docs at all. 29@PeterHilton •
  26. 26. 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) 30@PeterHilton •
  27. 27. ‘Beware of DRY, the evil siren that tricks you into abstraction’ Martin Thompson a.k.a. @mjpt777 31@PeterHilton •
  28. 28. @PeterHilton • Avoiding duplication at all costs may lead to incomprehensible abstractions. 32
  29. 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. 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 34@PeterHilton •
  31. 31. 35@PeterHilton • 6. Apply The Rule of Three before you remove duplication
  32. 32. 7. Accept that maintainable code costs more 36@PeterHilton •
  33. 33. How to maintain maintainable code
  34. 34. There’s not much point writing maintainable code if you don’t actually maintain it 38@PeterHilton •
  35. 35. 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’
  36. 36. 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) 40@PeterHilton •
  37. 37. 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
  38. 38. formal continuous code review
 (pull requests) review meetings pair programming
  39. 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 •
  40. 40. 8. Keep the codebase small 9. Increase refactoring effort as it grows 44@PeterHilton •
  41. 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.’
  42. 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 •
  43. 43. 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 47@PeterHilton •
  44. 44. 10.Write the minimum viable documentation
 (the rest is waste) 48@PeterHilton •
  45. 45. Summary
  46. 46. ‘Hell is other people’s code’* * Sartre didn’t actually say this 50@PeterHilton •
  47. 47. Summary 51@PeterHilton • 1. Recognise unmaintainable 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. Write the minimum viable system documentation
  48. 48.
  49. 49. @PeterHilton