Skip to Content
Author's profile photo Former Member

Properly Documenting Your Reports

Crystal Reports can make it easy to generate reports that display   complex data in an easy to read format. A well-designed report will   often be used throughout your company for many years to come. When   creating reports that will be used for the long-term, you need to   consider who will maintain them and how they are updated. An important   part of creating well-designed reports is planning for the future and   ensuring that it is easy for future report writers to maintain them.   Properly documenting and annotating your reports adds another level of   professionalism to them.

Proper documenting doesn’t need  to be an overly formalized, burdensome  requirement. Simply adopting a  few good habits early and making them a  part of your development  routine should provide adequate documentation  in most cases.

A  good start is to make a habit of using the Summary Info (File\Summary   Info…). Enter the Title as it should display in the report header. The   Subject field can be a short phrase or one-sentence description of the   report. Use the Comments to notate important information, including a   high level description of the objectives of the report, data sources   used (tables/views), plus filtering and grouping, etc. The Report Title   and Comments from the Summary Info are Special Fields that can be added   to the report itself. Also make sure to use the Author field so that a   future report writer knows whom to contact for questions.

Any  parameters used in the Selection Criteria should be displayed in the   Report Header or Footer. There is a field for this in the Special   Fields (Record Selection Formula). However, I prefer to embed the   Parameters in my group subtitles [Department {?Dept} for the Month of   {?Month} {?Year}]. The style used will be a personal preference of the   developer, but the goal is to clearly display the filtering applied to   the dataset.

A comment line may be added to any formula  (Formula Field, Conditional  Formatting, Record Selection, etc.) by  preceding the comment with two  slashes. It would be helpful in a  calculated field named Invoice_Total  to describe the calculation  [//Invoice gross plus tax and freight less  discount]. This may appear  to be self-evident in the formula (depending  on the naming conventions  in the database, but to another developer, or  even to yourself as time  goes by, this may prove helpful. Comments should be added to Formula  Fields that are created for use with  additional processing. For  instance, if a Boolean field is created for  use in a formula for  Conditional Formatting of a field, add a comment to  this formula  describing where the field is used, along with a little  context of what  is being evaluated.

I often insert comments between  sections of more complicated formulas to  break them up and make them  easier to follow. Comments can also be used  to temporarily eliminate  all or part of a formula during testing and  troubleshooting. If  altering a formula of a report in production, don’t  delete any code,  but wrap it in a comment instead to keep a record of  the change. Add a  comment with your name and date and identifying the  change made.

If you keep the documentation simple and apply it consistently, you will find that these practices will prove helpful over time.

Assigned Tags

      You must be Logged on to comment or reply to a post.
      Author's profile photo Tammy Powlas
      Tammy Powlas
      Too many times reports are created and not documented (guilty as charged).
      Thank you for the blog/post.
      Author's profile photo Former Member
      Former Member
      Really appreciating your suggestion.
      Documentation is very important, agreeing to the needs of documentaion which you have explained.
      Author's profile photo Former Member
      Former Member
      Simple version control by adding the version number at the end of the Comments of the Summary Info. In a formula just extract the last few characters of the Comments to drop the version number on the report.

      Another nice to have formula is one called "ReportHistory" - just a full commented box of in short what changed with the report.
      In addition any formula changed just has a nice comment of why it changed - thus building a trail over time for the next developer.

      I think the best mind set for working documentation is to think about how your company or the next developer will be able to develop the report once you are not there.

      Author's profile photo Andrew Baines
      Andrew Baines
      I wrote a simple app for a customer that ran through their BO Enterprise installation.
      It picked out each Crystal Report and extracted all the database and database table information. This was then inserted into a MS SQL Database so they could 'report on their own reports'. We also added stuff like number of instances and last run time.
      Their database changes frequently so change control for their reports is now much easier. On top of that, they realise just how many similar reports they have.

      Maybe in the next release I'll add a column that counts up the number of formulae that DON'T HAVE COMMENTS!! Then cross reference with the report's author. I think I'll need a big stick though.