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.