Time and again I find an example of correct usage to be the most helpful starting point for figuring out how something works. All too often we see people post requests for help with J code in these forums without providing any working example of what they have so far or an example of what they expect the output to look like in the case where they do not have working code.
Don's suggestion about "a series of NB.'s in the script indicating the usage" is a good one, especially for simple, one line examples. However, for longer examples, it's more convenient to put them in a noun using "0 : 0" as this simplifies cutting-and-pasting them into a session. See http://www.jsoftware.com/jwiki/NYCJUG/2013-01-08#The_Unreasonable_Effectiveness_of_Examplesfor an example. Also, examples of usage can double as test cases; for example http://www.jsoftware.com/jwiki/NYCJUG/code/processes.ijs , and " szRatio_eguse_" here: http://www.jsoftware.com/jwiki/DevonMcCormick/ParallelizedJCodeExamples#Parallel_Photo_Flipping. On Sun, May 18, 2014 at 12:31 AM, 'Bo Jacoby' via Programming < [email protected]> wrote: > Improve the program rather than the documentation. > > Den 4:49 søndag den 18. maj 2014 skrev Don Kelly <[email protected]>: > > > > > > > >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 <[email protected]> > 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 < > [email protected]>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 < > >>>> [email protected]> 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 <[email protected] > >: > >>>>> > >>>>> 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 <[email protected] > > > >>>> 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 < > [email protected]> > >>>>>>> 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 > > > > > > > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm > -- Devon McCormick, CFA ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
