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
