burns@latcs1.oz.au (Jonathan Burns) (09/05/90)
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 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
mjab@nanna.think.com (Michael J. A. Berry) (09/07/90)
In article <8703@latcs1.oz.au> burns@latcs1.oz.au (Jonathan Burns) writes:
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: any
Rank: any
Shape: any
.
.
.
In other words, I don't think the documentation appropriate to most other
languages is appropriate to apl. More useful documentation is "what is
this function for" (N.B. not "how does it do it, the APL says that ...).
-Michael
--
=============================================
Michael J. A. Berry
Internet: mjab@think.com
uucp: {harvard, uunet}!think!mjab
telephone: (617) 876-1111
=============================================dgil@pa.reuter.COM (Dave Gillett) (09/07/90)
Two things that I've tended to do, which I think have helped:
1. Devote some lines at the start of the function to verifying the shape/
size/type/number of the arguments, and taking appropriate action (which
might be signalling an error, or supplying a default for a missing left
argument). Mnemonic labels (eg. 'monadic:' and 'dyadic:') don't hurt.
2. Internal pieces of the package have a preceeding "Hungarian" (see
"Programmers at Work") component to their names. Typically something
like 'ILF*Log' (where * represents delta); in this case, 'I' is the
package (Ipsynch protocol), 'L' is the component (Logging of activity),
and 'F' is the type (Function). ILF*Log adds its right argument to the
log entry in ILV*Log, and ILF*Write stores it as a file component and
resets ILV*Log. If (!) I want code outside the package to be able to
store stuff in the package log, I'll add a function with an English
name ('Log' perhaps) that passes stuff to ILF*Log.
What APL do you use? Have you seen I.P. Sharp's "Logos" environment for
associating documentation and change journals with APL code?
Dave