How do You Document Globals You Use in a Project
Hi Developers!
InterSystems IRIS stores everything in globals and if we use ObjectScript classes to persist data class documents globals it uses in storage. But if you use globals for calculations, temporary storages, for special indexes or for some other purposes - how do you document it?
Possible options which come to my mind:
1. Macro
#define Array ^MyGlobalusage:
s $$$Array(1)=12. Class parameter
Parameter Array ="^MyGlobal";Usage:
s @(..#Array)@(1)=13. Documentation comment
Just document it to have it in a class documentation
/// ^MyGlobal is used to store my dataWhat do you do?
I never use hardcoded global names in code, all global references are defied as macros (preferable) or parameters (allows overloads).
Readme or documentation can provide some additional information on used globals but more as a reference.
I use option 1 (macros) with MAC routines and usually option 2 (parameters) with classes. I'd always use macros if it was possible to define them class wide without placing inside INC routines.
I prefer option 3 as the other options only makes your code more unreadable.
We could use <GLOBAL>^MyGlobal</GLOBAL> in the documentation, and write some script to generate a summary page of all classes that point to this global...