Designing Docassemble Interviews for Maintainability

1. Designing Docassemble Interviews for Maintainability Quinten Steenhuis, Founder, Lemma Legal Consulting @QSteenhuis

3. Why care? • Write code your future self can follow • Speed up development • Make your life easier

4. When does it matter? • When your interview is “big enough” • You start to get frustrated with navigating around it

5. “ Premature optimization is the root of all evil ” Donald Knuth

6. 5 Basic Techniques • Manage control flow in one place • Use good coding style • Use the “right” number of interview files • Use the right editor • Use object-oriented principles

7. “need” is considered harmful

9. Interview Flow Control • Use one mandatory code block to control program flow • Give the code block an ID • Use only simple branching logic in the control block

10. Use one control block • One place to look to understand program flow • Easily change the order of questions • Easily test different questions that don’t depend on earlier questions

11. Model Interviews https://lemmalegal.com/2019/06/17/designing-docassemble-interviews-for-maintainability-start-to-finish/

12. 2. Code with Style

13. Using “good” coding style • Use the id tag to label questions and code • Use the variable name standards • Use comments

14. Tag your blocks • Easy to find the question you need • Needed for Google Analytics • Aid in translation • Aid in debugging

15. “ The nice thing about standards is that you have so many to choose from ” Andrew Tannenbaum

16. Variable Name Standards • https://bit.ly/2IkW7mz (Michelle from Code for Boston) • On Slack: #structuring-code

17. 3. Divide and Conquer

18. Why do you need a separate interview file? • Question reuse • Translation (old style only) • Multiple simultaneous authors • Interview file is just “too long”

19. Use the right number of interview files • Start with 1 • Separate reusable questions • Keep a skeleton interview with control flow • Keep related questions/code together, but take advantage of search

20. 4. Get your edit on

21. Some popular (free) editors • VS Code • Atom • Notepad++ • Emacs? ViM?

22. Using an external editor • Plain text means you choose the editor • Better search/replace • Code completion • Split screen view

28. 5. Objectify your life

29. Why use Classes / OOP? • Make your code readable • Use advanced Docassemble features • Make your code more modular and reusable • Simplify your interviews • Write idiomatic code

30. Object oriented classes • Create once and use again • Build iteratively • Hide implementation details

33. Built-in classes to understand: • Individual • Address • Date • DAList

34. Built-in classes are used in • send_email(), send_sms() • map_of() • Pronouns/age functions • Collective/singular tense matching

35. Are classes easy? Truthfully, no. But it’s worth learning the basics. Start here: https://bit.ly/2wSTTVd

36. A common pattern: DAObject and DAList Asset / AssetList Individual / Individual List 3-4 attributes, a collection, and one-two methods that count or act on the attributes (such as sum)

37. Common Pattern #2: API query • Constructor that uses the Docassemble configuration to get an API key • A getter for each type of item retrievable by the API • A setter • Extend over time as you use more of the API

38. Quinten Steenhuis, Lemma Legal @QSteenhuis Questions?