How do You Document Globals You Use in a Project

Discussion

Evgeny Shvarov · Aug 18, 2019

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

usage:

s $$$Array(1)=1

2. Class parameter

Parameter Array ="^MyGlobal";

Usage:

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?

Discussion (3)1

Eduard Lebedyuk · Aug 19, 2019

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.

1 0

Alexey Maslov · Aug 20, 2019

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.

1 0

Danny Wijnschenk · Aug 18, 2019

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

2 0