Write Literate Programming Code

Literate programming is based on the premise that programs should be written to be read by humans first and computers second. Instead of organizing programs for the compiler or interpreter, we organize them for human understanding, breaking them into logical chunks that can be explained thoroughly.

• Write code as if it were an essay
• Explain the thinking behind your code
• Organize code in a way that’s logical for human understanding
• Present code in small, digestible sections

Following is an example on writing literate programming code for Commodore 64 BASIC.

• REM statements: For embedding documentation within code
• Structured layout: Organizing code in logical, functional sections
• External documentation: Maintaining companion documents
• Descriptive variable names: Making code more self-documenting

Using REM Statements

Primary in-code documentation tool

10 REM ****************************
20 REM * STAR FIELD SIMULATOR    *
30 REM * BY: YOUR NAME          *
40 REM * DATE: 02/05/2025       *
50 REM ****************************
60 REM
70 REM THIS PROGRAM CREATES A MOVING
80 REM STAR FIELD EFFECT USING
90 REM CHARACTER GRAPHICS

Section Headers

Clear section boundaries:

500 REM === INITIALIZE VARIABLES ===
510 DIM S(50,3): REM STAR ARRAY: X,Y,BRIGHTNESS
520 SC=1024: REM SCREEN MEMORY START
530 CC=55296: REM COLOR MEMORY START

1000 REM === MAIN PROGRAM LOOP ===
1010 GOSUB 2000: REM DRAW STARS
1020 GOSUB 3000: REM MOVE STARS

Inline Documentation

Attach explanations to inexplicit lines

300 X=INT(RND(1)*40): REM RANDOM X POSITION (0-39)
310 Y=INT(RND(1)*25): REM RANDOM Y POSITION (0-24)
320 B=INT(RND(1)*3)+1: REM BRIGHTNESS LEVEL (1-3)
330 P=SC+Y*40+X: REM CALCULATE SCREEN POSITION