Self-dcumenting code (was Re: Gforth, images, GPL...)

The thread turned into a discussion of minimalist coding styles,

documentation, comments, etc.

I would just like to remind everyone of a fine article by Michael

Ham, that appeared in DDJ in 1986. In it he discussed naming con-

ventions that lead to code that hardly requires comments because

it basically says what it does. One of the motivations for the

way

I do state machines (that is, convert a transition-table

represention

of the FSM directly into code) was to eliminate superfluous

comments.

They become unnecessary because the table _is_ the comment.

I wrote the FORmula TRANslator for the same reason, although it

is a necessary teaching tool for students familiar with languages

like BASIC, Pascal, fortran, C, etc.

It adds nothing to comment the linear equation solver

: }}solve ( A{{ V{ --)

initialize triangularize back_solve report ;

\ say a{{ v{ }}solve ; matrix a{{ overwritten, result in v{

(although the words making it up surely need commenting).

On the other hand, the Laguerre method for finding the roots

of a complex polynomial can be expressed as

: roots ( degree --) ( f: first_guess precision --)

LOCALS| degree | \ initialize

epsilon F! zz z!

BEGIN degree >root \ get a root

degree 1- \ reduce degree by 1

TO degree

b{ a{ n }mov \ create quotient polynomial

degree 2 =

UNTIL \ iterate

quadroots \ quotient is quadratic:

\ solve and display

;

This is by no means self-documenting, even with reasonable names

for the components. So it neads to have the steps commented.

--

Julian V. Noble

Professor of Physics

"Elegance is for tailors!" -- Ludwig Boltzmann