REBOL for COBOL programmers

Source code as corporate asset

Date written: October 15, 2012
Date revised:
Date reviewed:

This is a short note about all the comments you will see in the sample programs.

Making things last

A COBOL programmer probably has seen two phenomena worth thinking about. One is the longevity of COBOL systems. I myself have limited experience, but I have seen one billing system that was old when I first encountered it, and went on for over 30 years beyond that point, being modified from the days of punch-cards and magnetic tape to the days of datebases and the internet. Number two is the phenomenon of "spaghetti code," which is programming done with heavy use of the go-to statement and with sparse use of comments, resulting in programs that everyone is afraid to touch for fear of breaking them and not being able to fix them.

If a business buys a new truck, they take care of it to make it last, because it is a valuable corporate asset. Shouldn't software systems be thought of the same way? A computer program is not a programmer's personal creative project, but is an asset he has created for his employer that the employer might depend on for years to come. It should be built to last.

What does it take, in a computer program, to make it last? Some things that help are organization, layers of abstraction, avoiding unnecessary complexity, maybe a somewhat plodding approach to the code that avoids anything "efficient" but tricky, and useful comments. So, in the following examples, you are likely to see a level of commenting that many might consider excessive. The goal of all those comments is to keep the thoughts organized while writing it, to make it possible to come back later and understand it, and to make it possible for others to understand it. Not only that, it is hoped that the organization and level of commenting is enough that even if a person does not know REBOL at all, it should be possible at least to know, at any spot in the program, what is going on at that point.

An example

This is not the best example. It is something that came to me recently, and that I think shows the concept well enough. I found the following demo script on the rebol.org web site.

REBOL [
    Title: "Digital Clock"
    Date: 2-Apr-2001
    Version: 1.2.0
    File: %clock.r
    Author: "Carl Sassenrath"
    Purpose: "Displays a simple digital clock in its own window."
    Email: %carl--rebol--com
    library: [
        level: 'intermediate 
        platform: none 
        type: none 
        domain: [GUI] 
        tested-under: none 
        support: none 
        license: none 
        see-also: none
    ]
]

view layout [
    origin 0
    banner "00:00:00" rate 1 effect [gradient 0x1 0.0.150 0.0.50]
        feel [engage: func [face act evt] [face/text: now/time  show face]]
]

Looking at it now, I understand it, but I remember looking at programs like this when I was first learning REBOL, and having a strangely difficult time understanding them, even scripts of one or two lines.

I recently borrowed a script very similar to the above one and modified it for a specific personal use. As long as I was doing that, I thought I would comment it up my own personal standard, and maybe a little beyond, to suggest that it is a good idea to do everything a person can think of to make a program as understandable and maintainable as possible.

The script above was written by the author of REBOL. That is what REBOL code should look like. Since this is a demo, it might have a little less formatting than if it had been written for production, but it has a similar look to a lot of scripts on rebol.org so I think it is representative. The important part is the "banner" line, and one would think that no matter how obscure, it ought to be possible to understand a piece of code that occupies only two lines. However, I have had the experience of looking at a single line of REBOL code and not understanding it. So contrast it to the program I wrote from modifying something like the above.

REBOL [
    Title: "Exercise break timer"
]

;; [---------------------------------------------------------------------------]
;; [ This is an adaptation of a clock demo from the rebol.org web site.        ]
;; [ It runs a timer from a starting value down to zero, and then sounds       ]
;; [ an alarm.  It is used by SW to remind him to get out of his chair.        ]
;; [---------------------------------------------------------------------------]

;; [---------------------------------------------------------------------------]
;; [ Configurable items.                                                       ]
;; [ -------------------                                                       ]
;; [ TIMER-INTERVAL:  How often do you want to sound an alarm.                 ]
;; [                  This is a number of minutes and seconds, and REBOL       ] 
;; [                  recognizes it as such from its format.                   ]
;; [ SOUND-FILE:      "wav" file played every TIMER-INTERVAL minutes.          ]
;; [---------------------------------------------------------------------------]

TIMER-INTERVAL: 30:00
SOUND-FILE: %bushorn.wav 

;; [---------------------------------------------------------------------------]
;; [ Setup.                                                                    ]
;; [ ------                                                                    ]
;; [ Set a working counter to the timer interval.  REBOL will do "time         ]
;; [ arithmetic" with no problem.                                              ]
;; [ Load the sound file in preparation for playing, if it exists.             ]
;; [---------------------------------------------------------------------------]

COUNTER: TIMER-INTERVAL
SOUND-ENABLED: false
either exists? SOUND-FILE [
    AUDIO-MSG: load SOUND-FILE
    SOUND-ENABLED: true
] [
    alert rejoin [
        "Sound file "
        to-string SOUND-FILE
        " does not exist; no audio alerts"
    ]
    SOUND-ENABLED: false
]

;; [---------------------------------------------------------------------------]
;; [ Procedures.                                                               ]
;; [ -----------                                                               ]
;; [ START-TIMING:  This is done when the "Reset" button is clicked,           ]
;; [     to set the counter back to the timing interval so we can start        ]
;; [     fresh on our countdown to zero.                                       ]
;; [ PLAY-SOUND-FILE:  This is done when the counter gets down to zero.        ]
;; [     It plays an alert sound.                                              ]
;; [---------------------------------------------------------------------------]

START-TIMING: does [
    COUNTER: TIMER-INTERVAL
    MAIN-COUNTER/text: to-string COUNTER
    show MAIN-COUNTER
]

PLAY-SOUND-FILE: does [
    if SOUND-ENABLED [
        wait 0
        SOUND-PORT: open sound://
        insert SOUND-PORT AUDIO-MSG
        wait SOUND-PORT
        close SOUND-PORT
    ]
]

;; [---------------------------------------------------------------------------]
;; [ Main (and only) window.                                                   ]
;; [ -----------------------                                                   ]
;; [ Show the current time of day.  The timer interrupt of one second,         ]
;; [ combined with the "engage" function that is performed at the interrupt    ]
;; [ and redisplays the time, makes it look like the clock is running.         ]
;; [ Every time the "engage" function runs, every second, we reduce the        ]
;; [ counter, so it in effect counts seconds down to zero.                     ]
;; [ When we hit zero, sound an alarm and start over again.                    ]
;; [ Note:  It appears that "rate" and "feel" are not attributes of the        ]
;; [ window in general, but some item IN the window, in this case, the         ]
;; [ item of h1-style text that displays the time.                             ]
;; [ Note:  The stuff in parentheses is REBOL code that is run when the        ]
;; [ window is displayed.                                                      ]
;; [---------------------------------------------------------------------------]

MAIN-WINDOW: layout [
    origin 0                              
    MAIN-TIME: h1 red black (to string! now/time) 
        rate 1                            
        feel [
            engage: [                     
                MAIN-TIME/text: now/time          
                show MAIN-TIME                    
                COUNTER: COUNTER - 0:01   
                if COUNTER < 00:01 [      
                    COUNTER: TIMER-INTERVAL 
                    PLAY-SOUND-FILE         
                ]
                MAIN-COUNTER/text: to-string COUNTER 
                show MAIN-COUNTER                    
            ]
        ]
    MAIN-COUNTER: h1 (to-string COUNTER)             
    button "Reset" [START-TIMING]         
]

;; [---------------------------------------------------------------------------]
;; [ Begin. "First executable instruction," so to speak.                       ]
;; [---------------------------------------------------------------------------]

view MAIN-WINDOW

To a REBOL programmer, the script by Carl himself is a thing of beauty. To a COBOL programmer, or at least to some, the second is a thing of beauty, because of its organization and comments. No doubt it could be made shorter, but what is the benefit of its length? If you don't like the look of the window, you know exactly where the window code is. If it doesn't play a sound correctly, you know where to find the nine lines of code that play a sound. If the reset button doesn't work, you know the five lines of code that reset the timer.

If you are leaving source code behind for others, you should do what you can to make it last for them, so they can understand and modify it after your are gone. The examples in later pages are going to take this approach, at the risk of making something that true REBOL programmers might find replusive.

Code samples

Left-clicking a link below will give a result that will depend on your computer, your browser, and maybe in whether or not you have REBOL installed. You should get either a new window with the code displayed, or a dialog box for saving the file on your own computer, or "opening" the file which makes no sense in this situation. Right-clicking should give you a menu from which you can save it to your own computer.

Here is a little party favor, in the form of the above timer program. I use it to remind myself to get out of the chair every half hour because sitting is hazardous to one's health.