Documenting global variables

Marlan

I use global variables often and in typical project may have a half dozen or more variables. While there are many advantages to using variables over hard coding key parameters, I do struggle keeping track of what the variables mean and how they are used. Especially when returning to a project after some time. Without any documentation, I end up spending a chunk of time with the global search to review usage of the variables.

One approach I've used is to document the variables in a wiki page but that's hard to keep consistent with the variables and is a pain to have to go back and forth between the variables screen and the wiki page.

Ideally, we'd be able to include comments in the JSON definition of the variables. That'd be a nice improvement for sure!

As it may be helpful to others, I'll post an approach I've been using that works reasonably well in a reply to this post. Would welcome other ideas for how to keep track of what variables mean.

Marlan

Marlan

My current approach is include an additional global variable called variableDefinitions which I use define sub-variables which contain definitions. This way the definitions are right in the JSON where I need them and it's pretty easy to keep the definitions in sync. Here is an example:

{
  "varOne": 1,
  "varTwo": 2,
  "varThree": 3,
  "variableDefinitions": {
    "varOne": "Definition and usage noates for varOne",
    "varTwo": "Definition and usage noates for varTwo",
    "varThree": "Definition and usage noates for varThree"
  }
}

tim-wright

@Marlan
Thanks for this post. Something I typically do - which is not always sufficient by itself - is to try to name all my variables such that it is somewhat clear on reading the name. This sometimes leads to variable names that are a little longer than I'd like - and isn't always sufficient. I like your idea about keeping documentation about the variables handy right along side them. Thanks for the tip.

Mark_Treveil

Personally, I prefer the above solution to the comments-in-variables approach.

I'm sure Microsoft provided something similar 20 years ago for customising Intelli-sense.

Implementing some tooltip-type info in the editors would be cool, no?