When you start designing larger Docassemble interviews (in the thousands of lines), it becomes more important than ever to take the right approach. The presentation above was given at Docacon 2019 and discusses 5 key techniques for maintainable interviews:

1. Manage control flow in one place
2. Use good coding style
3. Use the “right” number of
   interview files
4. Use the right editor
5. Use object-oriented principles

This post is a supplement to the presentation which includes additional references for self-directed learning.

Examples of managing control flow

https://github.com/GBLS/docassemble-income/blob/master/docassemble/income/data/questions/financial_statement.yml

See lines 35-51 and lines 54-92. These represent two independent blocks of questions in a logical order, that can be used as a module inside a different interview. To use, for example, the questions that ask about you, your spouse, and any household members, you could add this YML file to your list of includes, and then refer to the variable household_questions. Docassemble will go through every question in the code block until it reaches the line that sets household_questions to true.

Coding Style Guidelines

Variable name standards:
https://github.com/knod/docassemble-standards/wiki/Standardized-Definitions-For-Variable-Names

Use short, descriptive names. Use _ to separate words. Refer to the list of existing variable names, and use them wherever possible. If it’s possible to have multiples of any item, use the standard plural to make it clear. E.g., child -> children.

In general, the style guidelines prefer using built-in Docassemble Classes to represent things like people, addresses, and more. This will keep your code idiomatic and consistent with the work of others.

To see what a coding style guideline might look like, you might also be interested in PEP8, the Python style guideline.

Splitting your interview file

See the presentation.

Use the right editor

Here are three good editors for a new Docassemble developer to try as an alternative to the Docassemble Playground:

1. VS Code (Windows, Mac, Linux)
2. Atom (Windows, Mac, Linux)
3. Notepad++ (Windows only)

Command-line diehards might also check out VI Improved (VIM) and Emacs.

Learn object-oriented programming

You can start with my introduction to object-oriented programming.
https://www.nonprofittechy.com/2018/09/12/object-oriented-programming-for-document-assembly-developers/

Some real Docassemble classes to take a look at:

• https://github.com/GBLS/docassemble-income/blob/master/docassemble/income/income.py
• https://github.com/nonprofittechy/docassemble-MACourts/blob/master/docassemble/MACourts/macourts.py
• https://github.com/nonprofittechy/docassemble-AnnotatedIndexBuilder/blob/master/docassemble/AnnotatedIndexBuilder/annotatedindex.py
  
• https://github.com/nonprofittechy/docassemble-ssa/blob/master/docassemble/ssa/ssa.py

Some further reading:

• https://realpython.com/python3-object-oriented-programming/
• https://www.datacamp.com/community/tutorials/python-oop-tutorial