Self-dcumenting code (was Re: Gforth, images, GPL...) 
Author Message
 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



Tue, 18 Mar 2003 03:00:00 GMT  
 
 [ 1 post ] 

 Relevant Pages 

1. GPL & gforth

2. self-replicating-code, self-replicating-messages

3. Chuck Moore vs. lesser programmers (was: Gforth, images, GPL)

4. GPL and Copying Code

5. CRC-32 native code for DOS GForth 0.5.0

6. GForth & Obfuscated Source Code

7. TCL code to extract image captions and image keywords - ImageMagick

8. TCL code to extract image information from uploaded image file

9. Displaying and Image in a simple report - What am I missing

10. I am not able to read a barcode from a image

11. Self Modifying Code

12. self modifying code in J

 

 
Powered by phpBB® Forum Software