[Jprogramming] Code clarity

[Don Kelly]

This looks great -in that the listings do describe things fairly well as 
most are simple and useful.  However
in some cases things are still unclear.
an example is sminfo
It  appears that it simply shows a  result in a separate box but unless 
one  uses sminfo a=: foo y ,  vs sminfo  foo y , the result is lost. so
how does this become of any more use that smoutput a=: foo y or ]a=: foo 
y ? or even foo y ?

What would be nice would be something like sminput which would allow 
entry of data  in the form
x=: sminput  data
similar to what is available in APL.
It may be there but I haven't found it.

Don Kelly

On 15/01/2014 1:43 PM, Ian Clark wrote:
> @jasmine - it's hard to know how to do better than
>     edit 'stdlib'
> or for a particular verb:
>     edit 'splitstring'
> because the scripts are well-commented. And they have the vast advantage of
> keeping themselves up-to-date -- a biiiiiiiig problem with jwiki.
>
> The contents of _z_ are documented here (mostly):
> http://www.jsoftware.com/jwiki/stdlib.ijs
> but there's no corresponding:
> http://www.jsoftware.com/jwiki/strings.ijs
> --perhaps there should be?
>
> I think it boils down to: where *would* a newbie expect to look? That's a
> function of his/her imagination. The jwiki is littered with half-hearted
> attempts to address this problem:
> http://www.jsoftware.com/jwiki/Guides
> http://www.jsoftware.com/jwiki/Guides#faqs
> http://www.jsoftware.com/jwiki/Guides/Getting%20Started
> http://www.jsoftware.com/help
> Perhaps the best of the Guides needs a link adding to the top line of the
> last of these?
>
> There's no substitute for a good newbie who's thick-skinned enough to ask
> the dumb questions. Hard to find and worth far more than diamonds.
>
> On Wed, Jan 15, 2014 at 2:50 AM, Pascal Jasmin <godspiral2000 at yahoo.ca>wrote:
>
>> actually a documentation effort on the z profile names would be quite
>> helpful.
>>
>>
>> ________________________________
>> From: Don Guinn <donguinn at gmail.com>
>> To: Programming forum <programming at 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 <rauldmiller at 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 <donguinn at 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
>