camillebaldock/tech_debt.md

## tech_debt.md

      
    Raw
  

              tech_debt.md
            
          
    Smartdown/smart-answers tech-debt and potential improvements

Testing and confidence


Enforce unique flow name between Smartdown/SA
Smartdown lint/validate

Check all ref'd nodes exist
Check no orphan nodes
Run in SA CI


Smartdown Scenarios

Feature flag to disable artefact lookup
What should we cover/not cover?


Smart Answer features


Deprecate hint
Remove has_foo? methods
Remove subtitle field
Allow both prefix and suffix labels

Check if this is an acessability issue


Documentation


Smartdown readme
How to do a transition
Language feature guide (not as a readme)
General architecture, layers
Glossary: flow, node, element, predicate, state, evaluation

Misc


Otherwise predicate in graph not useful
should be NOT(previous branch)?

Smart Answer app


Adaptors

Group presenters in adaptor module
distinct from other libs


Put smart_answer presenters in module to avoid name clash

Rename smartdown adapt[o|e]r
Lack of testing

create minimal test harnesses as a start


Pass artefact into controllers
Response naming/handling

smart answer vs smartdown
multiple questions per page vs single
checkbox multi response


lots of contoller/logic duplication for SA/Smartdown
namespace smart_answer rake tasks, to avoid confusion
Tests running incredibly slowly
use human names in graph
multiple folders for plugins: keep or change?

Smartdown


Naming

Predicates, vs nodes, vs elements
Non predicate constructs, conditional, interpolation
should identifier parse definition include ?

confusing named predicate (which is bool)
vs name of a state var, eg question_1?


too many things called state
flow input, directory input, input set - wat?


Predicates

clarify naming of predicates
split predicates vs language models
predicates as booleans/operators
distinguish functions
scope predicates to Rules only
add variable 'predicate', evaluate to state var
OR predicate
Useful for simplifying some SPL node rules


Testing

Lack of acceptance tests


Move conditional evaluation into model

Simplify/replace resolver


Make nodes evaluate(state)able? eg

node.evaluate(state) resolves conditionals, interpolations, etc
Could replace NodePresenter


Abstraction

Push element parsing into models/node transform as much as possible
Go through API models and enumerate direct element use


Read/understandability

Overly complex interpolation class


Potential bugs

Test nested function parsing, not just calling


Answer object: use of to_s, humanize, value is odd and inconsistent:

stop using forwardable approach
explicitly document what to_s, humanize, value (what is for URLs/representation in outcomes, smartdown response input etc...)


Monkey-patching comment in Smartdown: improve comment and open a possible parslet issue

Smartdown API


DirInput / FileInput, expects .read
Push Element filtering examples from API into Model layer

even better, in to transform, super simple structs


Smartdown shouln’t take y for started, ui concern
Flow naming convention, Gem assumes cover sheet, App dir
Better directory structure

distinguish Node > Element


Review API models and restrict to core responsibilities

Could they be re-written as structs?


Plugins

one file per question
stop using class methods for everything
distinguish run-time vs build time by which methods take arguments
judicious memoization during initialization of each plugin set


Smart Answer transition


calendar support(?)
tool to convert rb/yml flows to smartdown
tool to convert rb/yml tests to scenarios
support all question types

money
checkbox
date of birth


custom validation: custom date ranges?

Check if this is fixed


Handle missing need_id in Smartdown, don't raise error