It’s Day 19 of the 30 Days to Become a Better Monarch Modeler series and one of the last Monarch features to comment on is, well, commenting.
To date in this series we’ve touched on, if not elaborated on, virtually every aspect and feature of Monarch software. Given the possible complexity of the modeling work with all of these tools at our disposal, in some situations it might not be immediately obvious why and how we use certain Monarch objects.
In an age when practically every action within an organization is to be auditable and “transparent”, it just makes sense – as good modeler builders – to clarifying our actions as early as possible. That auditor is bound to come knocking on our door sooner or later; best take steps to make the process as easy as possible.
Where to Add Comments
You can add descriptive text to almost every item in Monarch, including definitions for:
- Templates
- Painted fields
- Project exports (not on-time exports)
- Bookmarks (though those are usually comments of a different intended purpose)
- All four types of calculated fields
- Both kinds of filters
- Sort orders
- User-defined functions
- Address blocks
- External lookups, and
- Summaries
Additionally, formulas in calculated fields (and edited measure calculations within summaries) can even contain comments embedded in the formula by enclosing the text within a /* */ combination.
Finally, under the File menu or via the “i” icon in the toolbar, you can (and should) add descriptions for the model itself and the project too (if applicable).
How to Add Comments
It’s very easy to add comments to Monarch objects. Click the “Comment…” button, type some text and OK it. Your comment will be saved in the model file.
Comments Prohibited
Well “prohibited” is a bit strong, but there are areas in Monarch for which we cannot currently add commentary. Maybe in the next version we’ll be able to describe why we needed to make elections and/or configuration changes for the:
- Page setup
- Field list
- Object links
- Tree definition
- Multi-column region definition
- Dialogs accessed from the Options menu, and
- Summary design preferences
What to Write
While documenting models with comments is a relatively new process, good software programmers have been at it for years, and we take some tips from the type of comments that that group often compose.
Programmers are usually an efficient bunch, so their comments are often pretty brief, and they choose what to comment on carefully rather than spending just as much time documenting as they do coding.
There’s a school of thought they have that refers to “self-documenting code”. That basically means that the intention is that the entirety of the program code should be clear enough to understand without injecting purely descriptive text. I find that methodology to be a bit extreme, and frequently unsuccessful. But as Monarch modelers we can employ the approach in a somewhat limited fashion. All we need do is carefully name our objects at every opportunity as meaningfully as possible. That alone would be a great start to a documentation effort.
When programmers do introduce comments though, the best comments don’t so much describe the step by step work as they do the reason for selecting the chosen method implemented.
Clarifying a commission calculation by restating its components isn’t nearly as helpful as pointing out why it must be calculated as it is, or how a component was derived or where the end result will be used or which group or even individual needs this information. Which of these would you rather encounter for a Commission field?
- “Calculates commission on the sales for this record.”, or
- “The commission calculation both employs a regional factor and a multiplier value (which changes seasonally) because the sales manager wants to recognize, and compensate equitably for the variable sales challenges throughout the year across the country.”
Your Task for Today
Since you’re intent on becoming a better Monarch modeler, today you’ll open the last three models that you’ve developed or revised and add appropriately placed comments that add insight to the model. Keep in mind that your comments might be read by an auditor, someone who is new to your model and needs to make changes for whatever reason, or even you – long after you’ve forgotten how or why you did what you did.
Additionally, today you will commit to yourself that in your future modeling work, you will take the extra few minutes to document as necessary.
Have you noticed how Monarch uses the commentary you supply to make it easier to review and select the various objects that accept comments? If not, go back and have a look around.
Clearly a Cut Above
When you take the time to add valuable and astute internal documentation to your models, your models should be viewed as being a better work than those models prepared by someone who didn’t go that “extra mile”. Ask a programmer for his opinion of the programmer who created the code that he’s maintaining that contains not a single comment.
Your work in adding transparency will be a crystal clear reflection of your ability to excel with Monarch.
—
Continue your commitment to Become a Better Monarch Modeler with Part 20 of the series, or review Part 18.
