Scripting Documentation Tips & Best Practices?

Document created by eric on Jan 9, 2019Last modified by eric on Jan 9, 2019
Version 3Show Document
  • View in full screen mode

When I was adding some comments to a script, trying to document its perform-script dependencies, I realized script names could change, but the comments would not change automatically. It reminded me of philmodjunk's DIGFM presentation on How Brittle is Your Database?

Then I had an "aha!" moment. Why not just copy and paste all the Perform Script steps next to the comment and disable them like this?:

#This script only sets up the loop for its dependencies.

#Script dependencies:
// Perform Script [ “FTF - Check EI” ]
# Which depends on the following:

// Perform Script [ “FTF - EI Calculation” ]
// Perform Script [ “FTF - Determine If Eligible”; Parameter: $eiResult ]

// Perform Script [ “<unknown>” ]

Then if the script name ever changes, the documentation automatically changes. It also easily provides some context, e.g. If the script dependency happens to be Perform Script or Perform Script on Server, or if there were parameters. The documentation will even reflect <unknown> if the script is is deleted, and documentation script references will show even in the Database Design Reports.


I'm guessing this technique might have been already obvious to others (or dismissed as problematic perhaps), which causes me to ask:

What other scripting documentation tips and best practices do other experienced developers have that we should all know?

8 people found this helpful