Below you can find some additional explanations on the documentation header used in a Stored Procedure:
Tags
The script will pick up lines that start with: -- DID -
This is the identifier with which a documentation line should start. This is an abbreviation of ‘Data Integration Documentation’. Behind this part an indicator should follow specifying what is documented in the line. The maximum length of the entire line should not exceed 200 characters. This to avoid truncation of the content.
The tags can be repeated multiple times. The content will be concatenated in the script based on the sequence in which they occur in the routine.
The tags shouldn’t be specified on a specific location in the routine. They can appear anywhere in the script. Avoid specifying the tags above the ‘CREATE/ALTER’ part of a Stored Procedure as the system has troubles reading the Stored Procedure when it is registered in Engage.
The following elements are picked up currently:
Author
This specifies the author of the original script.
Example : -- DID - Author: Peggy Heyvaert
CreationDate
This should contain the original creation date of when the routine was created.
Example : -- DID - CreationDate: 2017-02-28
Version
Indicates the version of the script. We will follow the ‘X.Y.Z’ scheme of versioning:
- Major version numbers change whenever there is something significant, a large or potentially backward-incompatible change to a software package.
- Minor version numbers change when a new, minor feature is introduced, or when a set of smaller features is rolled out.
- Patch numbers change when a new build of the software is released to customers. This is normally for small bug fixes or the like.
If a routine isn’t used yet in production the ‘Major’ version number should be ‘0’, once it is being used in production it should be updated to at least ‘1’.
Example : -- DID - Version: 1.2.3
Description
Contains the description of the routine. Be as complete as possible so that it is clear what the routine will do without the necessity of reading the code.
Example : -- DID - Description: Function that will capitalize the first character of each word of the passed input string.
Exceptions
If the routine can throw a specific error or multiple ones, they should be specified in this element. If there is more than one error thrown by the applications explicitly then these should be placed on a new line each.
Example:
-- DID - Exceptions: Record not found.
-- DID - Exceptions: Record is already expired.
BusinessRules
All specific business rules should be specified in this element. You can specify multiple business rules by just repeating the ‘DID’ part. You can use this everywhere in your routine as it isn’t restricted to the header so use it extensively to document different parts of the routine.
Example :
-- DID - BusinessRules: Check whether the record only occurs once in the list.
-- DID - BusinessRules: Check whether the record is still active.
LastModifiedBy
This should contain the name of the person who did the last change on the routine.
Example : -- DID - LastModifiedBy: Hermans Oliver
