Path: utzoo!utgpu!news-server.csri.toronto.edu!cs.utexas.edu!sdd.hp.com!zaphod.mps.ohio-state.edu!rpi!batcomputer!munnari.oz.au!mel.dit.csiro.au!latcs1!burns
From: burns@latcs1.oz.au (Jonathan Burns)
Newsgroups: comp.lang.apl
Subject: Coding Standards
Message-ID: <8703@latcs1.oz.au>
Date: 5 Sep 90 01:26:37 GMT
Reply-To: burns@latcs1.lat.oz.au (Jonathan Burns)
Organization: Comp Sci, La Trobe Uni, Australia
Lines: 84


Is there such a thing as a coding layout standard for APL?

I've been hacking out little graphics demonstrations, but now I want to
build a library of functions and constants. To keep track of existing
functions, I fill out a form:

...........................................................................

Calling form:  Same as the header line, i.e. what's after the del when editing.

Arguments: 
	Name:
	Type:
	Rank:
	Shape:
	Description: i.e. content, purpose etc.

Result:
	As above. 
	Shape: Given if necessary as a function of the argument shapes

Function description:
	Purpose of the function; i.e. a few words on the mathematical
	semantics of it all. 

Examples:
	{left argument} <- {shape} rho {ravel}
	{right argument} <- ""
	{result} <- ""

...........................................................................

This is enough for present purposes, but is surely quite inadequate for
large projects, say 50 functions or more. Some of the things I'm going
to _forget_ with 50 functions are:

1)  Shape and type conformability.

    That's in the form already. 

2)  Axis usage of arguments.

    e.g. This argument is a point list. Do I expect coordinates along
    the first axis or the last? This leads to a data-structure description
    of the shape, implying that I should be naming standard shapes.

3)  Global variable use.

    Obviously the global dependencies of a function have to be recorded.
    There is also the messy issue of functions assigning to globals,
    which seems to me a bad thing to do, but hard to avoid unless one
    adopts a rigorously functional coding form (which is my preference).

4)  Error conditions.

    At least, we need a list of error messages with the input conditions
    that produce them. Error messages need a standard form as well.

5)  Internal analysis.

    Line-by-line description of functions is very important in APL,
    single lines being so powerful and all.

6)  Naming standards

    There is a need to develop modular collections of functions; and the
    global names of a module need to be kept distinct from any other
    module's names. (The lack of scoping support for modularity may be
    the biggest gap between APL and structured programming).

And there has to be more that I haven't thought of. Question is, has 
anyone worked through the issue of standards? 

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Jonathan Burns        |  They finally discovered that the ONE thing
burns@latcs1.oz       |  they just could not _STAND_ was a smartass
Computer Science Dept |  commenting decompiler ...
La Trobe University   |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~