Comments

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 !
! ==============================================================================