[Jprogramming] Understandable J

Sun May 18 02:49:43 UTC 2014

I find that putting code with lots of explanatory NB.'s  and maybe a 
how-to  paragraph as a noun in a script is essential. This also works 
for little code snippets than may prove useful in the future (and 
sometimes with variations listed).  Examples also help.
This is not only an aid to me, but to others who may use the code. This 
came from past APL experience where I would look at something I wrote 
and wondered what I did. Starting from scratch is nice but if the hard 
work has been done, why do it again
except to improve on  the approach?
There are 2 ways:
1)intersperse comments within multiline verbs  to help interpretation of 
the line
2)provide a noun such as "howN'
and example of this is the following definition from an Essay on Newton 
Raphson
where the following is given

  N=: 1 : '- u % u d. 1' (which could be given a better name)

this could be followed by a series of NB.'s in the script indicating the usage
NB. (_2+*:)N ^:c]xo solves x^2 =2 using c iterations starting form a guess xo
or with more Nb. for more detail.

Don Kelly

On 15/05/2014 11:36 PM, robert therriault wrote:
> Thanks Raul,
>
> I am happy with some of the progress that I am making in my projects  (and occasionally programming as well), but I like the poetry of J and in that way part of the challenge is placing the context through the examples. Without that context a poem is just pretty words on a page and a tacit expression without examples may not even reveal its valence.
>
> I think that there are opportunities in combining good test driven development with the rapid prototyping abilities of J -- but first I am playing with J Labs as a medium of expression, education, art etc.
>
> Cheers, bob
>
> ps. I appreciate the support for my work. The fact that I am a terrible programmer does not keep me from making terrible programs that explore neat ideas. Life's too short to let a lack of talent hold you back :-)
>
> On May 15, 2014, at 11:10 PM, Raul Miller <rauldmiller at gmail.com> wrote:
>
>> I would not knock "starting from scratch" as a bad thing. Arthur Whitney
>> has been known to do that, for example.
>>
>> I think it matters more what you are accomplishing and your ability to make
>> that useful for other people.
>>
>> Thanks,
>>
>> -- 
>> Raul
>>
>>
>> On Fri, May 16, 2014 at 2:07 AM, robert therriault <bobtherriault at mac.com>wrote:
>>
>>> I am a terrible programmer, but I have found that including comments that
>>> have examples of what the entity should do, are usually enough for me to
>>> figure out what is going on.
>>>
>>> Without that ... I usually start from scratch, as that is faster and less
>>> frustrating.
>>>
>>> I really am terrible at programming.
>>>
>>> Cheers, bob
>>>
>>>
>>> On May 15, 2014, at 10:52 PM, 'Bo Jacoby' via Programming <
>>> programming at jsoftware.com> wrote:
>>>
>>>> "how does one write understandable J?" One does not write understandable
>>> J! One writes as compactly as possible, and if it needs to be understood
>>> it's parts are investigated piece by piece. Understandability is not a
>>> property of text, but rather a property of relationship between text and
>>> reader. / Bo.
>>>> Den 3:51 fredag den 16. maj 2014 skrev Don Guinn <donguinn at gmail.com>:
>>>>
>>>> What is easy and obvious depends so much on one's background. Several
>>> years
>>>>> ago we tried to teach a woman, at the time in her 80's, how to use a
>>>>> Windows computer. Total failure. The real problem was that she could
>>> see no
>>>>> use in or reason to use a computer. She had no interest in learning it.
>>>>>
>>>>> Anyone who thinks that today's computer technology is intuitive, obvious
>>>>> and easy should go to an old folk's home and try to teach them to use a
>>>>> smart phone. But for a four-year-old. Piece of cake.
>>>>>
>>>>>
>>>>> On Thu, May 15, 2014 at 6:10 PM, Raul Miller <rauldmiller at gmail.com>
>>> wrote:
>>>>>> I am convinced that most code is not understandable to most people,
>>>>>> regardless of the language it is written in. When I look at how the
>>>>>> computer industry has progressed, I see this more and more. People
>>> write
>>>>>> huge amounts of code, don't document it very well, then other people
>>> use
>>>>>> arbitrary bits of it and things sort of just freeze at that point.
>>>>>>
>>>>>> Personally, also, when I read code in any language, I do not feel I
>>> really
>>>>>> understand it until I see what it does to representative data.
>>>>>>
>>>>>> So clear descriptions, simple data, and good labels are where I would
>>> focus
>>>>>> most of my efforts in making code readable. And I would also expect
>>> that
>>>>>> most of my code is going to be unread by most people (and I'll get
>>> dinged
>>>>>> for utterly random stuff by people who do read it).
>>>>>>
>>>>>> I think the point of readability is: you are going to need to be able
>>> to
>>>>>> fix it, yourself, when it breaks, so you need to make it readable for
>>>>>> yourself. And for that purpose, coming back and trying to read it a
>>> month
>>>>>> or so after you've written it can be a good exercise.
>>>>>>
>>>>>> Also, I've found that documenting code is a great way of making code
>>>>>> simpler. It's quite often the case that it's easier to change the code
>>> to
>>>>>> be easy to document than it is to document some coding quirks that
>>>>>> originally seemed to be a good idea. So if you want readable code,
>>> another
>>>>>> good thing to do is have a technical writer (or at least someone
>>> reasonably
>>>>>> literate) work with the programmer to document it for some audience.
>>>>>>
>>>>>> Of course, the most important thing is making sure that it works.
>>>>>>
>>>>>> Thanks,
>>>>>>
>>>>>> --
>>>>>> Raul
>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> On Thu, May 15, 2014 at 5:23 PM, Kip Murray <thekipmurray at gmail.com>
>>>>>> wrote:
>>>>>>
>>>>>>> How does one write understandable J?  I offer my newt adverb below
>>> which
>>>>>>> uses spaces to promote understandability.
>>>>>>>
>>>>>>> Another technique might be Linda's "bottom up" style of first showing
>>>>>>> pieces then putting the pieces together.  What are your techniques?
>>>>>>   Please
>>>>>>> illustrate.
>>>>>>>
>>>>>>> We would like at least to understand our own code when we come back to
>>>>>> it!
>>>>>>>     NB. Newton's method
>>>>>>>
>>>>>>>     newt =: 1 : 0
>>>>>>> t =. y
>>>>>>> h =. 1 % 512
>>>>>>> whilst. t ~: s do.
>>>>>>>     s =. t
>>>>>>>     t =. s - +: h * (u s) % (u s + h) - u s - h
>>>>>>>     h =. h % 2
>>>>>>> end.
>>>>>>> t
>>>>>>> )
>>>>>>>     (2 - *:) newt 2   NB. Find root of 2 - *: near 2
>>>>>>> 1.41421
>>>>>>>     (2 - *:) newt _2  NB. Find a root near _2
>>>>>>> _1.41421
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Sent from Gmail Mobile
>>>>>>> ----------------------------------------------------------------------
>>>>>>> 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
>>>
>> ----------------------------------------------------------------------
>> For information about J forums see http://www.jsoftware.com/forums.htm
> ----------------------------------------------------------------------
> For information about J forums see http://www.jsoftware.com/forums.htm
>