Just a short post today! Here are some handy hints on how to put developer comments within reports. I always say to my team “if it looks like you’ve done something unusual, then make sure you comment it”. I was told that code is written once but read many times.
It may appear that there isn’t any specific comment functionality within reporting. But with some clever use of existing functionality, there are ways we can add developer comments.
Query Data Item Comments
Often you want to comment a query data item, maybe it’s a complex calculation. You can use the Cognos Macro Language comments functionality to do this. Wrap the comment with #/*comment*/#. For example, add a comment to this data item expression:
This macro comment technique only works within query data item and filter expressions. It will not work in report expression data items (such as conditional styles, variables).
Query Separators
If you have a query with a lot of data items, you may want to group them together to make it more obvious what is going on. (Until we get folders within queries, or folders for queries) I have found separator data items the best way of doing this. I usually make my separator data items look like:
>---------------- Subject ----------------<
The query below only has a few data items, but it shows the intent (by no means am I saying you should group your data items like this, it’s just a silly example):
The expression for these separator data items is just a simple ’1’:
As these separator data items are not used within the data containers within the report they will not add any cost to any query. (Advanced authors will be rushing to the comments to tell me that if this a nested query, then they will be included within the query so will add to the cost of the query. This is true, but as the calculation is a simple number it won’t be significant.)
In Page Comments
You may want to comment on the report page itself. This is also achievable. For example:
You can put as many such comments anywhere on the page.
These comments are simply a formatted block with text pasted within it.
Most importantly, the box type of the block is set to None. This makes the comments disappear from the report output. Report developers can also toggle the comment blocks on and off whilst authoring by using the Visual Aids Show Hidden Objects option:
Switching this off makes the above report look like:
It is important Report Developers remember to enable this visual aid in order to see any comments a previous author may have added.
To make adding comments even easier for Report Authors consider adding a Comment Class to a report that is used as a ‘Report style reference’ by other reports. If you have never used a style reference report, I urge you to look into this. It is the simplest way to give all your reports a common look and feel by maintaining all your classes within a single report.
By adding a comment class, a report author can turn anything into a comment by simply adding the comment class to the object:
This ensures all comments look the same across all reports and formatting something as a comment is a few click process.
Overall Details / Version History etc.
You can also add page to a report to contain anything you want; in any format you want. For example, within the reports I author the first page within the report is Developer Comments.
The contents of the Developer Comments page can be any format you want. Here is an example that you may want to follow.
By being the first page in the report this is the first thing Report Authors will see when they edit a report.
The page is prevented from appearing in the report output by using a render variable. First create a Boolean variable that will always be false. I name this variable False.
I use the expression ‘1 = 0’, after all 1 will never equal 0.
Set the Render variable property of the Developer Comments page to the new False variable.
As this variable will never be true, the page will never render within any output.
How do I comment… ?
The above shows some simple techniques for commenting queries, specific parts of pages and the overall report.
I have yet to find simple techniques for adding comments to report expressions. Report expressions can be found within variables, conditional styles or even text items. If anyone knows of a way to do so then please comment (see what I did there) below!
If you have any additional comment techniques, then also comment below.
#IBMChampion