That would be wonderful!!!
Don Kelly
On 14/01/2014 6:50 PM, Pascal Jasmin wrote:
actually a documentation effort on the z profile names would be quite helpful.
________________________________
From: Don Guinn <dongu...@gmail.com>
To: Programming forum <programm...@jsoftware.com>
Sent: Tuesday, January 14, 2014 4:15:08 PM
Subject: Re: [Jprogramming] Code clarity
So many names in the z locale. I wonder what that looks like to a newbe.
Take a name like splitstring. Got a pretty good clue from its name. Where
is it defined? Exactly how can one use it? Easy enough for someone familiar
with J to just look at its definition then play with it a little. Maybe go
find the script in which it is defined and look for comments. But a new
user would probably just give up and not use it. But if there were a
description of its usage somewhere it would e many times larger than the
definition.
For one experienced with J such documentation is unneeded. But what about a
newbe? They are the ones who need a jump start so they don't become
frustrated.
On Tue, Jan 14, 2014 at 8:01 AM, Raul Miller <rauldmil...@gmail.com> wrote:
I have also struggled with documentation, and not only in the context
of apl and/or j.
I sometimes wonder, though, how important it really is. So much of the
skill of computer programming comes through seeing the code through
experimentation and seeing both the code and its variants in action.
Quite often, I find that the code makes a lot more sense when I see
what it is doing. (And, all too often, that winds up being "nothing
useful" so then I wonder if there are other cases where it would be
useful.)
Anyways, writing documentation is a mentally and socially intensive
task, and I have the utmost respect for people that can do it well.
And good documentation gives valuable perspectives and insight into
the underlying code. But... it's a struggle for me.
Thanks,
--
Raul
On Tue, Jan 14, 2014 at 9:47 AM, Don Guinn <dongu...@gmail.com> wrote:
It's always been a mystery to me why it is OK to spend several hours (or
sometimes days) analyzing several pages of FORTRAN or C but when reading
a
few lines of APL or J which do the same thing I must grasp it in a few
minutes or I start feeling overwhelmed. But I have written similar
"run-ons". Why? Because I can set up test data and add a little at a time
to a line or a few lines, executing it and looking at the results as I
go.
I have to force myself to break that monster up into more readable
chunks.
I can't do that in other languages as I have to compile or whatever, So I
tend to write all the code then start debugging.
Then comes documenting. I put a brief description of what it's for and
expected arguments. Then add references and why the code does what it
does.
I try not to repeat describing what the code does. But then I end out
with
comments many time larger than the code. That just seems weird!
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
