NYCJUG/2005-05-10

indexing help, unit tests, interface design, commenting convention, organizing J tips, Howard Peelle

Meeting Agenda for NYC JUG 20050510

1. Group project: report on assignments
    a. Harteg - initial screen
    b. Dan - persistence of information
    c. Jim - indexing/Rosetta Stone - how to unearth implicit info,
        e.g. see "SelectDefaultCase.txt".
    d. John - GUI + command line
    e. Devon - short-term focus-> prototype sufficiently useable for
       everyone to start using it.

2. Assignments: going forward - what next?
    a. Unit test examples?  See following for how we might evolve these:

annualize=: 4 : 0
NB.* annualize: given returns over equal-length periods, approximate yearly returns
NB. covering same time-span.
   'dypd dyyr'=. x.           NB. Days per period, days per year
   rets=. y.                  NB. Returns "r" per period.
   xpr=. dypd#(>:rets)^%dypd  NB. avg return for each day
   ptn=. (#xpr)$dyyr{.1       NB. partition into years worth of days
   <:*/&>ptn<;.1 xpr          NB. rets per year: from "1+r"->"r" form
NB.    100 261 annualize 10$0.01   NB. 1% every 100 days, 261 business days/year
NB. 0.026310532 0.026310532 0.026310532 0.021827017
NB.    1.01^2.61                   NB. Easy alternate calc since all rets are equal
NB. 1.0263105                      NB. matches all but last year which was not full

NB. Equivalent test might look like this:
NB. 9!:19]1e_12 [ svct=. 9!:18 ''  NB. Many multiplications->lower precision
NB. assert. (<:1.01^2.61)*./ . = }:100 261 annualize 10$0.01
NB. 9!:19]svct
)

    Additional tests like arguments should be integer?

3. Learning and creating learning materials: "case" in point:
   how do we specify a default case in "select" statement?
   See "SelectDefaultCase.txt".

   General organizing principles - main categories?
       Rosetta Stone
       Utilities: what are general types?
       Web site?

Proceedings

Individual Projects

Jim spoke about an automatic indexing program to help get a handle on the voluminous J documentation. John stressed the difficulties with this as he has had much experience doing work like this with bibliographies. However, an indexer would be less labor-intensive than manual recapitulation or explanation of the documentation, if perhaps not as useful.

I brought up a recurring problem of the sort an indexer would not solve: the implicit information lost in the richness of J. For example, there was recently traffic on the forum about specifying a default case in a switch statement. The documentation alludes to how to do this but does not lay it out even though this is a commonly desired thing to do in a switch statement. (See File:SelectDefaultCast.txt.)

Jim's "action item" is to work on an indexer.

John had taken it upon himself to work on how to combine the best of both GUI and command-line or scripted interfaces. A GUI aids a novice but presents an obstacle to automation and remembering what's been done. John presented some work on "inert" a function to combine both immediate and delayed execution.

NB. Immediate, logged and delayed execution
linear=: 5!:5

NB. [x] u inert y---> '[x] u y'
inert=: 1 : 0
y=. y.
u=. y.
(linear<'u'),' ',(linear<'y')
:
x=. x.
y=. y.
u=. u.
(linear<'x'),' ',(linear<'u'),' ',(linear<'y')
)

   plus=: + inert ; +
   a=. i.3
   b=. >:i.3

   a plus b             NB. Returns script; result
+-------------+-----+
|0 1 2 + 1 2 3|1 3 5|
+-------------+-----+
   a plus"0 b
+-----+-+
|0 + 1|1|
+-----+-+
|1 + 2|3|
+-----+-+
|2 + 3|5|
+-----+-+
   ". &> {."1 a plus"0 b
1 3 5

The idea here is that commands activated within the GUI could keep a log of their invocation. This could allow a GUI session to be captured as a script, allowing us to use both the GUI and the command-line.

I'm continuing to try to get us to to focus on a short-term deliverable of a prototype sufficiently complete for everyone in the group to start using it. My "action item" for the next meeting or before is to come up with a "Vicki" use-case, where "Vicki" is our target user of the backup system. Having a specific person to think about may help us target the interface design.

Interface Design

Thinking about interface issues, we looked at a couple of articles. One, "Controlling Your Environment Makes You Happy" by Joel Spolsky [1], in which he outlines some basic design rules for user interfaces. He starts with an anecdote which leads him to a psychological theory called "Learned Helplessness". This relates to user interface design with the insight "that a great deal of depression grows out of a feeling of helplessness: the feeling that you cannot control your environment."

Any of us who use software all day can relate to this feeling. Expanding on this theme, I told about a study I'd read in the "Communications of the ACM" in which researchers tested peoples' responses to some software which had deliberate flaws in the interface, making it unnecessarily difficult to use. I forget the point of the study but one observation stuck with me: no one complained about how bad the software was. The researchers attributed this to people being so used to poorly-designed software that it wasn't worth mentioning.

We can do better, especially when a tool like J makes it so much easier to add the many small aspects to an interface that make it enjoyable and not frustrating to use.

Spolsky's essay is well worth reading for many reasons. One of his first points illustrates that user expectation is important. He does this by presenting a scenario with an imaginary user because when "thinking about user interfaces, it helps to keep imaginary users in mind. The more realistic the imaginary user is, the better you'll do thinking about how they use your product." His example points out how the supposedly simpler Macintosh interface can be frustrating to an expert PC user because of the PC user's habits and expectations.

This also illustrates another point I tried to make by way of an essay called "Street Mathematics" [2] by Keith Devlin: different people think differently. There is no single way that different people learn or understand things. This point addresses the risk of thinking in terms of a single imaginary user: we want to allow multiple ways to do the same thing. We also want to present the same material in different ways.

This idea of doing the same thing in different ways also emphasizes the usefulness of allowing both a GUI and command-line version of an interface.

Code Example: Incorporating Unit Tests

I presented a small example of the early evolution of a unit test. It starts with some comments showing how to verify the code for a simple case and goes on to suggest how to set up an assertion equivalent to the test. We talked about how to join or separate the test with or from the code. The consensus seemed to lean toward separate test scripts, perhaps incorporating a naming convention and using a distinct namespace like "test". (See File:Annualize.ijs for the example I gave and File:TestscriptsEG.txt for how Hui does it.)

Commenting Convention

I continue to push the idea of commenting each function with an initial line of intent - what the code is supposed to accomplish - using a special comment convention "NB.* <function name>". This is not my invention - I may have gotten it from Kirk Iverson or Chris Burke.

Also, I like to end a function with an example use. Having the example at the end makes it handy to grab and modify if you list the function in the J session.

Having the special initial comment, with "NB.*", is useful once a script starts to have many functions because you can grep out these lines and put them at the beginning of the file as a table of contents.

Organizing J Tips

We've all found nice J idioms - Jim called them "gems" - we'd like to keep track of and share but how do we organize these? I suggested we each create about three "bags": general categories in which to put useful tips we've learned. These could be directories or files depending on how extensive they get.

A project for the group, then, is for each of us to come up with the "bags" we'd find useful. Two we came up with at the meeting were "gems" and "common tasks". This latter would include things like explicit mention of how to specify the default case in a switch statement (which is an empty case, e.g. "case. do.").

Howard Peelle to Speak in June?

I'm talking to Howard to see if he can come down next month to show off his book and give a talk, perhaps on learning J. We may not be able to meet on our regular day (2nd Tuesday of the month) depending on his schedule.

Scan of Meeting Notes