Cognos Analytics

 View Only

No Further Comment. (or adding developer comments in reports)

By Marc Reed posted Wed February 21, 2024 08:06 AM


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.





Mon March 04, 2024 03:35 AM

@Philipp Hornung I wonder if the C12 Data Module metadata translation functionality would help with bringing in external text for DM descriptions, screentips etc.
I don't have a C12 version to play with so I don't even know if these attributes are part of that functionality. But if they are, then it is certainly worth a look.

The one thing I do in a data module to help document is create a calculation called 'Audit v2024 03 04'. This just contains a simple '1' calc, but a macro comment block that details the changes made within the DM. I update the calcs name to an appropriate time stamp. As we version control through Dev/Test/Prod this is an easy way of seeing which version of a DM has made it to through the different environments.

Fri March 01, 2024 12:10 PM

Thanks for this overview! These are essentially the techniques we also use. 

A related topic are comments on metadata. I've just opened an idea regarding SQL COMMENT ON import into data modules: 

Do you also have best practices for comments on metadata/data modules? 

Thu February 22, 2024 04:16 AM

very nice overview, thanks