How to document app flow (with method/function references) for a refactor?

I’m currently refactoring and redesigning an app that’s build with Blaze, before was pre 1.3 imports and fairly messy, 60% of the code unused, no documentation, etc.

I’m probably around 70% done with the refactoring but I’m currently hitting a roadblock, by realizing there are details of the code that are just too complicated, and I must have missed 1 or two parts of the code that should not have been deleted while cleaning up. I’m now trying to document the app (in-code) but also then from better understanding the fine-grained details of the code, I’d like to create a flow chart of what the app does with references of what is happening, like which method is called here, e. g.:

user logging in -> 
is onboarding complete? -> 
yes/no: do this or that (as defined in router.js, in global beforehook), 
call these functions/methods, run those helpers, etc.

I’ve done lots of high level flow-charts for apps from a product perspective before, I want to write this now for the technical side. I have no experience what would work well here, can you recommend a type of flow chart / how to approach this to make sure I can “swiftly” document the code, so that I but also others will be able to better grasp what’s going on in the app?

Edit: I would also like to add comments to those actions, such as

whether onboarding is complete is defined and checked in user.status.value == 'scoutedable' 
1 Like

II don’t know if I’d attempt a detailed document of the code. Is it highly unlikely anyone would ever read it–or maintain it as code changes?

One idea might be to start with some tests. Then as you refactor you could run your tests to check for breaking changes. A CI pipeline could help automate this I.e. In heroku you can set it up to auto deploy to staging on commit to your branch and run CI tests automatically. then you could just commit refactorings in small batches and have testable atomic deploys. That would help you isolate where the breaking changes happened when tests fail.

Generally I think you just have to study the code until you understand it before you can refactor successfully. Try to do it in phases. Radical refactoring is dangerous. So shorten your cycle times and work in small interations. Remove obviously unused code (linting can help with that), rename things (It’s hard to guess what “scoutedable” could mean, are you sure the concept is clear there?), refactor functions according to Single Responsibility Principle, basically make only small refactoring you feel highly confident about. Doing this will improve the code a bit and more importantly it will help you get your head around the application functionality so they you can gradually expand and make larger refactorings with increased confidence. Don’t get too ambitious. There is much value is the cumulative effect of small iterations and short cycle times.

https://tobeagile.com/2010/10/27/why-short-iterations-work/

3 Likes

Thanks, great advice. I agree, unit tests would have been really helpful. Too much stuff just breaks here and there, What I’ve started doing is:

  1. Start documenting code pieces bit by bit
  2. Create a UML chart with all the user and system actions + adding some references to functions/methods in there
  3. Next step will be unit tests and selenium tests hopefully.

Linting also helped greatly to discover unused stuff as you’ve said.