[Jprogramming] Code clarity
John Baker
bakerjd99 at gmail.com
Tue Jan 14 21:32:50 UTC 2014
Oops the link I meant to post is:
https://github.com/bakerjd99/joddumps
On Tue, Jan 14, 2014 at 3:28 PM, John Baker <bakerjd99 at gmail.com> wrote:
> This was one of the motivations behind JOD. Here's a quick snapshot of
> something I am working on right now. The dictionary tracks and displays
> appropriate "documentation" on demand. Of course you still have to do a
> little work - entering a brief statement of what a particular word is about.
>
> The addon distribution does not include all these dictionaries but you can
> get most of them (nonwork) from
>
> https://github.com/bakerjd99/jacks
>
> require 'general/jod'
>
> NB. list available dictionaries
> od ''
> ┌─┬────┬─────┬──────┬───┬──────┬────┬─────┬────┬────┬───────┬─────┐
> │1│docs│image│import│jod│joddev│junk│mwecc│play│smug│smugdev│utils│
> └─┴────┴─────┴──────┴───┴──────┴────┴─────┴────┴────┴───────┴─────┘
>
> NB. show currently open dictionary summaries
> did ~ 0
> ┌─┬──────────────────────────────────────────────────────────┐
> │1│┌─────┬──┬─────┬─────┬───────┬───────┬──────┬────────────┐│
> │ ││ │--│Words│Tests│Groups*│Suites*│Macros│Path* ││
> │ │├─────┼──┼─────┼─────┼───────┼───────┼──────┼────────────┤│
> │ ││mwecc│rw│330 │9 │20 │0 │19 │/mwecc/utils││
> │ │├─────┼──┼─────┼─────┼───────┼───────┼──────┼────────────┤│
> │ ││utils│ro│331 │7 │17 │0 │9 │/utils ││
> │ │└─────┴──┴─────┴─────┴───────┴───────┴──────┴────────────┘│
> └─┴──────────────────────────────────────────────────────────┘
>
> NB. list groups (modules)
> de grp ''
> APL385UnicodeTest CdmColumnXref CdmTester CountryWide
> CwfRegression CwfResearch FuzzyAlerts GridDemo
> ICD MathJaxDemo Outliers RecodeSchedZ
> UltimateLosses base64 boxopen bstats
> buildutils dbi dbicreate dbimodelsample
> dbisqlite dbitester dewhitejscript dllutils
> earthdistances htmthorn ijfFrsf jdemo2
> odbcREF remdots rwtabd socketsREF
> sunmoon trig unicode wordformation
> xmlutils
>
>
> NB. brief summary of words in a group
> hg 'bstats'
> ┌────────┬──────────────────────────────────────────────────────┐
> │antimode│finds the least frequently occurring item(s) in a list│
> │dev │deviation about mean │
> │dstat │descriptive statistics │
> │freqdist│frequency distribution of numeric items │
> │fuserows│opens and catenates boxed lists on the last axis │
> │geomean │geometric mean of a list │
> │harmean │harmonic mean │
> │kurtosis│kurtosis │
> │lsfit │coefficients of polynomial fitting data points │
> │mean │mean value of a list │
> │median │median value of a list │
> │midpt │mid-point │
> │mode2 │finds the most frequently occurring item(s) in a list │
> │movgmean│moving geometric mean │
> │movmean │moving mean │
> │q1 │first quartile │
> │q3 │third quartile │
> │round │round y to nearest x (e.g. 1000 round 12345) │
> │skewness│skewness │
> │ssdev │sum of square deviations (2) │
> │stddev │standard deviation (alternate spelling) │
> │var │var │
> └────────┴──────────────────────────────────────────────────────┘
>
>
> On Tue, Jan 14, 2014 at 3:15 PM, Don Guinn <donguinn at gmail.com> wrote:
>
>> 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 <rauldmiller at 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 <donguinn at 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
>>
>
>
>
> --
> John D. Baker
> bakerjd99 at gmail.com
>
--
John D. Baker
bakerjd99 at gmail.com
More information about the Programming
mailing list