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
