@jasmine - it's hard to know how to do better than edit 'stdlib' or for a particular verb: edit 'splitstring' because the scripts are well-commented. And they have the vast advantage of keeping themselves up-to-date -- a biiiiiiiig problem with jwiki.
The contents of _z_ are documented here (mostly): http://www.jsoftware.com/jwiki/stdlib.ijs but there's no corresponding: http://www.jsoftware.com/jwiki/strings.ijs --perhaps there should be? I think it boils down to: where *would* a newbie expect to look? That's a function of his/her imagination. The jwiki is littered with half-hearted attempts to address this problem: http://www.jsoftware.com/jwiki/Guides http://www.jsoftware.com/jwiki/Guides#faqs http://www.jsoftware.com/jwiki/Guides/Getting%20Started http://www.jsoftware.com/help Perhaps the best of the Guides needs a link adding to the top line of the last of these? There's no substitute for a good newbie who's thick-skinned enough to ask the dumb questions. Hard to find and worth far more than diamonds. On Wed, Jan 15, 2014 at 2:50 AM, Pascal Jasmin <godspiral2...@yahoo.ca>wrote: > actually a documentation effort on the z profile names would be quite > helpful. > > > ________________________________ > From: Don Guinn <dongu...@gmail.com> > To: Programming forum <programm...@jsoftware.com> > Sent: Tuesday, January 14, 2014 4:15:08 PM > Subject: Re: [Jprogramming] Code clarity > > > So many names in the z locale. I wonder what that looks like to a newbe. > Take a name like splitstring. Got a pretty good clue from its name. Where > is it defined? Exactly how can one use it? Easy enough for someone familiar > with J to just look at its definition then play with it a little. Maybe go > find the script in which it is defined and look for comments. But a new > user would probably just give up and not use it. But if there were a > description of its usage somewhere it would e many times larger than the > definition. > > For one experienced with J such documentation is unneeded. But what about a > newbe? They are the ones who need a jump start so they don't become > frustrated. > > > On Tue, Jan 14, 2014 at 8:01 AM, Raul Miller <rauldmil...@gmail.com> > wrote: > > > I have also struggled with documentation, and not only in the context > > of apl and/or j. > > > > I sometimes wonder, though, how important it really is. So much of the > > skill of computer programming comes through seeing the code through > > experimentation and seeing both the code and its variants in action. > > > > Quite often, I find that the code makes a lot more sense when I see > > what it is doing. (And, all too often, that winds up being "nothing > > useful" so then I wonder if there are other cases where it would be > > useful.) > > > > Anyways, writing documentation is a mentally and socially intensive > > task, and I have the utmost respect for people that can do it well. > > And good documentation gives valuable perspectives and insight into > > the underlying code. But... it's a struggle for me. > > > > Thanks, > > > > -- > > Raul > > > > On Tue, Jan 14, 2014 at 9:47 AM, Don Guinn <dongu...@gmail.com> wrote: > > > It's always been a mystery to me why it is OK to spend several hours > (or > > > sometimes days) analyzing several pages of FORTRAN or C but when > reading > > a > > > few lines of APL or J which do the same thing I must grasp it in a few > > > minutes or I start feeling overwhelmed. But I have written similar > > > "run-ons". Why? Because I can set up test data and add a little at a > time > > > to a line or a few lines, executing it and looking at the results as I > > go. > > > I have to force myself to break that monster up into more readable > > chunks. > > > I can't do that in other languages as I have to compile or whatever, > So I > > > tend to write all the code then start debugging. > > > > > > Then comes documenting. I put a brief description of what it's for and > > > expected arguments. Then add references and why the code does what it > > does. > > > I try not to repeat describing what the code does. But then I end out > > with > > > comments many time larger than the code. That just seems weird! > > > > > > ---------------------------------------------------------------------- > > > 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
