Evgeny Shvarov · Aug 18, 2019

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 ^MyGlobal


s $$$Array(1)=1

2. Class parameter

Parameter Array ="^MyGlobal";


s @(..#Array)@(1)=1

3. Documentation comment

Just document it to have it in a class documentation

/// ^MyGlobal is used to store my data

What do you do?



0 269
Discussion (3)3
Log in or sign up to continue

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...