Add comments to your reports

Make your reports easier for yourself - and others - to understand

Have you ever used an unusual technique in a report, only to find yourself completely baffled by it when you re-visit the report a few weeks later? Or maybe you've written a clever formula, but have found that you cannot for the life of you remember what the formula was all about when the time comes to modify the report.

Programmers are familiar with this situation, and have adopted a well-tried method of coping with it: commenting. By adding explanatory notes and comments to their programs, they provide themselves - and other programmers - with valuable reminders of what the program does and how it does it. The same technique can - and should - be applied to reports.

If your report is in any way unusual or complicated, you owe it to yourself to document it in the form of comments. You will also be doing a favour to any other Crystal Reports users or developers who might have to work on the report in the future.

Where to put them

So how do you go about commenting a report? One option is to enter your comments in the report's Document Properties box, which you get to by selecting Summary Info from the File menu. As you can see from Figure 1, this dialogue includes a Comments field, which you can use to hold any text you like. Whatever notes or comments you type there will show up in the Summary pane of the File Open dialogue (Figure 2). You, or another developer, can therefore view the comments without even having to open the report.

Figure 1: You can store short comments in the Document Properties window.

Figure 2: The comments show up in the File Open dialogue (click the Properties button on the dialogue's toolbar to show the comments).

The problem with this approach is that the comments are not particularly easy to edit or to read. The Document Properties window only shows five short lines at a time. The File Open dialogue is more spacious, but the comments cannot be edited in that window. Also, your colleagues will have to know where to look. If they are not aware of this feature, they might never see the comments. Still, this type of commenting might be a good option for short comments if it is used consistently by all members of your team.

Comments as text objects

Another option is to add comments in the form of text objects placed on the surface of the report. To prevent them showing up in the report itself, you can either suppress them, or you can place them in a report section which is itself suppressed. In fact, you can create a (suppressed) report section for the express purpose of holding comments. Such comments will be easy to edit and their presence will be obvious to anyone working on the report in design mode.

But, again, this approach is more suited to shorter comments. If you have comments that contain more than a few lines of text, they will soon clutter up the design surface and make it much more difficult to see the important parts of the report.

Comments in formulae

Our preferred approach is to create a special formula to hold the comments. The Crystal formula language supports commenting, and this is a valuable feature in its own right. It is always good practice to place comments within your formula code, to remind yourself what the formula does and how it works. Our technique takes this one step further, by putting all our report-wide comments in a special formula (which we call, unsurprisingly, Comments).

Using Crystal syntax, you can add a comment to a formula simply by typing two forward slashes in the formula code. Whatever text you then type on the rest of the line will be treated as a comment (and will show up in green in the formula editor). Comments have no effect on the functioning of the formula, nor do they impact the performance of the report. If you prefer Basic syntax, just type an apostrophe instead of the two forward slashes.

Figure 3 shows an example of a dedicated Comments formula. In this example, the comments are used to explain the overall structure of the report. They could also be used to show the report's version history, the names and contact details of its designers, a copyright notice or any similar details that users might find useful.

Figure 3: A formula is a good place to write comments.

Make it obvious

Once you have created the Comments formula, it will show up in the list of formulae in the Field Explorer, from where it can be accessed in the usual way. Even so, the existence of the formula might not be particularly obvious, and not everyone will think to look for it.

So, as a final step, we place our Comments formula in the report itself, along with an accompanying text object to draw attention to it. For good measure, we format the formula and text object with an eye-catching font and colour (see Figure 4).

Figure 4: The existence of the Comments formula will be obvious to anyone working in design mode.

We normally put these objects near the left edge of the Report Header band, where they will be immediately visible to anyone working on the report in design mode. To prevent them showing up when the report is previewed, exported or printed, we conditionally suppress them, using a formula that always returns true (such as 1 = 1). (If we suppressed them unconditionally, they would appear in light grey in design mode, and would therefore be less obvious).