Don't forget about "Note". I like to use the right argument as a title or a one line description. Then put the detailed description below. This gives the possibility to provide self-documenting by redefining "Note" to extract information for help. And we still have the left argument to play with.
On Mon, May 19, 2014 at 9:01 AM, Devon McCormick <[email protected]> wrote: > 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 ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
