All applications need some kind of code commenting mechanism for maintenance purposes. With programming languages it is easier; however with tools it can be a little tricky to put comments. In this recipe, we will see different options around putting comments within a report that will be invisible from users but accessible to the developers.
- For the first technique to put comments and notes within a report and hide it from users, go to Page Explorer and create a new page. Call it Comments.
- Open this new page and drag text items on it. Write all the comments about report here (description, functionality, notes, special cases, and so on).
- Now go to Condition Explorer and create a new Boolean variable. Define the expression as:
1=0. Name this variable asRender_Comments. - Go to Comments page. Open the Render Variable property and connect it to
Render_Commentsvariable.
- Run the report. Notice that Comments page is never rendered.
- Now we will see another place to put comments. For that go back to Cognos Report Studio and open the main report page.
- Drag a new HTML item on the report header. Define the HTML code as follows:
- Run the report to test it. Notice that the comment doesn't appear in the report, but if you view the source code of the HTML output, you can see the comment.
- Finally, let's see the XML commenting option. For that, copy the report to the clipboard.
- Add following line in the beginning of code:
<!-- This is XML Comment -->
- Copy the whole specification again and paste it back into Cognos Report Studio. Save the report.
- Run the report to test it.
We have seen three ways of putting comments and notes within report in this recipe. All of them work fine and do their job.
Some developers don't like creating a new page or HTML item for storing the comments, as this means creating some objects on the report that are not required. These objects form a part of the XML specification and they are validated and parsed every time the report runs.
Following that belief, we can put the comments in the XML specification itself. That way comments are completely ignored by the Studio while validating and parsing. However, it does mean that each time the developer needs to refer to or update the comments; he will have to copy the report specification in XML editor.
Having a separate page (first approach) is a very clean method. However, it doesn't allow you to put comments in-line. So if you have a comment or note specific to a column or prompt, you can't just put it near that object and make it noticeable.
I personally find the HTML comment method to be the best. By having one HTML item in the page header, I can put all the commentary about that page in there. Also, I can create specific HTML items to hold particular object related notes and put it near that object. Also, later on, if I am running any report and want to see the comments, I don't have to open it in Cognos Report Studio. Instead, I can just look at the HTML Source Code and it will have those comments inline.
I will leave it to your own experiments and preference to decide which one to follow in your team.