Advice on Structuring Long Macros

[August]

I found some advice that spoke to me in the following thread, so I'm extracting it to be able to find it again and so that it might reach a larger audience. Here's the original question:

Structuring long, complex macros

Hi everyone! I have been searching the forum and surprised I couldn’t find any existing topics about this… Like many of us who try to get the most out of KM, I have some HUGE daisy-chained macros that consist of groups inside groups of grouped actions, plus use of external macros via “Execute Macro” action. I end up getting pretty lost in the macro which can create that foggy feeling in my head when it comes time to revisit and adjust a macro. Does anyone have any tips or tricks about how to …

And here's the answering advice:

@Mark

• “Reset variables” at the beginning is good practice.
  Better practice: make it a sub-macro.
• “Repeat Actions” is another good candidate to be a sub-macro.
  Make it better by passing a variable for the number of times to repeat the loop.
• Lots of “Search and Replace” actions.
  Instead, have one sub-macro and pass a variable for what to replace.
• On a flow chart, the code above would look like a long and winding road; difficult to maintain.
  Better practice: use a tree structure with lots of thin branches.
  Or hub-and-spoke structures with small, controlling macros at the center.
• To improve macro names change to noun first, verb after.
  Instead of “Fix Quiz Options for Core Quizzes” …
  make it, “Quiz Options: Fix Core Quizzes”.
  That way every macro acting on “Quiz Options” will appear together in the macro list.
  For naming macros, nouns (targets of action) are almost always more important than verbs (what the action does).
• Old programmers’ “Rule of Thumb” to make future maintenance easier:
  One action : One comment

[Joel_Rendall]

Thanks for resurrecting this, August! The biggest piece of the advice I've carried with me these past years for some reason, (in KM as well as task and project management apps) is the noun:verb approach to naming things.