From: Alfie Costa (agcosta@gis.net)
Date: Mon May 01 2000 - 01:18:13 CEST
Here's a possibly off-topic question about 'ash' programming, plus a few naive
speculations...
Is there any good minimalist commenting style for showing what types of
input/output are done by 'ash' functions? Or maybe competing schools of style?
Examples from other languages:
In C there is:
Int AddInts(Int a, Int b)
Which tells you and the compiler that the function AddInts takes two ints from
the stack, and returns another. Strictly speaking that's not really a C
comment at all, it's a C necessity; but what I'm interested in here is only
what it tells the forgetful programmer.
In Forth there is:
: AddInts ( a b -- c ) ..... ;
Which tells you the same thing, though the compiler doesn't understand it --
it's solely for the programmer's benefit.
Now in 'ash', there's no stack, and a function can do simple I/O from the
command line, stdio, and errorlevel codes. This makes three possible sources
of input, which is harder to diagram than just one stack.
In 'file' I've experimented with comments like:
AddInts() # a b
# returns: c
{ .... }
...but wonder if there is a better way, or if perhaps such comments are not the
proper way of mu, or worse than what they're intended to cure?
Shots in the dark:
AddInts() # CL( a b -- c ) ERR( -- f ) IO( -- )
...where 'f' stands for a true/false flag. CL stands for 'command line'; ERR
for 'error code, or what $? returns'; and IO stands for 'input/output', for
what streams, if any, the function accepts.
AddInts() # a b -- c ; -- f ; --
...minimal.
AddInts() # a b - c ; - t/f ; -
...more minimal, but with 't/f' for true/false.
AddInts() # i1 i2 - i3 ; - t/f ; -
...the first letter abbreviates what type of data it might be, with numbers to
tell them apart. Examples might be '$' for string, 'is' for 'input stream',
'bis' for 'binary input stream', that sort of thing. The possibilities for
being cryptic seem endless...
MyCat() # (fn) - ; - t/f ; (is1) - is2
...in this case the parenthesis mean 'optional'. (fn) would be 'optional
filename', (is1) would be 'optional input stream'. One problem with this
notation is that there's nothing to show that 'is2' depends on one of those two
options.
Hopefully this is enough to get across the idea, right or wrong...
Caveat: this post, however charismatic, should not be construed as an attempt
to start a cult or religion. I had just forgotten what some of my old code
did, and wished I didn't actually have to re-read it.
---------------------------------------------------------------------
To unsubscribe, e-mail: mulinux-unsubscribe@sunsite.auc.dk
For additional commands, e-mail: mulinux-help@sunsite.auc.dk
This archive was generated by hypermail 2.1.6 : Sat Feb 08 2003 - 15:27:14 CET