The language of the comments should be English; avoid bad words.
You should use the following style for comments:
(It is only a recommendation)
! ============================================================================== ! One sentence description of the purpose of the script ! ------------------------------------------------------------------------------ ! Input Parameters: ! par1: description of the parameter (integer) ! par2: description of the parameter (1 / -1) ! par3: description of the parameter (0 / 1) ! ... ! Output: [if a macro returns values] ! : description of the value (type) ! : description of the value (type) ! [ ... NSP]: original stack elements ! Remark: ! Longer description. ! Note for the caller ! ==============================================================================
Any code can come only after this.
! ============================================================================== ! Section name ! ==============================================================================
The length of the full comment line is 80 characters.
For the subroutines you should always explain the meaning of non-trivial parameters and the return values, if any.
E.g. for indices always indicate the range (starts from 0 or 1, any special values, etc.).
Example in the Subroutines section.
You should always indicate with the TODO keyword if you leave something unfinished, it’s easy to search for later:
n = 5 ! TODO: set initials; it will be computed from the length
You can also put optional section descriptions in between the lines of the source code, beginning at the current tab depth.
You can also add short explanations to the end of the source line by adding a tab at the end; or, if there are more of those, you can align them with tabs.
You should always add comments:
- for unusual solutions,
- if it would help others understand the code more quickly,
- and if something is forbidden or not recommended for others.
Optional (others will be thankful) if it helps in any way.
Do not let the comments break the rhythm of the code, or the merits of the code.
When commenting a coherent code block, you may use the following format:
! == code block name ===[ statement1 ... statementn ! ]=== code block name ===
This facilitates the isolation of the block by the look plus some editors support the search for the matching bracket by a shortcut
(e.g.: ctrl + ] in Microsoft Visual Studio)
Comment the end of ‘if’ statements if there are many code lines between if and endif as follows:
if condition1 then ... if condition2 then ... ! many statements ... endif ! if condition2 endif ! if condition1
Some script types (Forward and Backward Migration Scripts especially) have a recommended form of separators and structures.
For examples, see the library or the section called Basic Technical Standards.