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.
