[Jprogramming] Understandable J

Sun May 18 04:31:41 UTC 2014

Improve the program rather than the documentation. 

Den 4:49 søndag den 18. maj 2014 skrev Don Kelly <dhky at shaw.ca>:

>
>
>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
>>
>
>----------------------------------------------------------------------
>For information about J forums see http://www.jsoftware.com/forums.htm
>
>
>