The language of the comments should be English. Avoid profanity.
Start comments at the indentation of commented code, otherwise indentation-based code folding is impossible.
Short comments can be placed on the line of the code, separated by at least one tab.
Add comments:
- For unusual solutions.
- To help others understand the code more quickly.
- For limitations, unhandled circumstances, special circumstances handled before.
- Label constant numeric identifiers with a comment – or consider using a descriptive constant variable when used more than once:
- abstract integer values (options / choices / flags)
- index of embedded pictures
- integer subroutine labels
- array indices (except coordinate indices)
Avoid using TODOs and commented code lines.
Use the following styles for comments:
Script/subroutine header
! ==============================================================================
"Subroutine":
! ------------------------------------------------------------------------------
! Description
! input:
! variable description if not self-explanatory
! output:
! variable description if not self-explanatory
! ==============================================================================
Dictionaries
Write a comment about dictionaries used in or returned from subroutines at least once in the file, according to this template:
! name
! .key
! .subkey1 .subkey2 (type) comment
! ? .optional_key
! .array[]
! .subkey
Where key type is not written explicitly, it is a real number (floating-point value). Keys that have subkeys – marked with indentation – are dict or array type.
For example:
! circle
! .bSpecial (bool) contains special points
! ? .specialPoints[]
! .x .y
! .center
! .x .y
This means the following code is valid:
if circle.bSpecial then
for i = 1 to vardim1(circle.specialPoints)
line2 circle.center.x, circle.center.y,
circle.specialPoints[i].x, circle.specialPoints[i].y
next i
endif
Code blocks
if ...then
...
! ==========================================================================
! Section
! ==========================================================================
...
if ...then ! sometimes
...
! ----------------------------------------------------------------------
! Sub-section
! ----------------------------------------------------------------------
...
! ==============================================================================
end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end ! end !
! ==============================================================================