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
