J/HouseStyle

This page is a sandbox for discussing the goals of the J community on RC, and to develop guidelines and standards for J code to help achieve those goals. The result will be a J house style.

goals

1. increase the usage of J by:
   • increasing its exposure (coverage of tasks)
   • showcasing its strengths (terseness, clarity of solutions)
   • making examples accessible to newbies (e.g. judicious naming of code segments)
2. provide resource of "good" example J code to J learners
3. provide a Rosetta stone for explicit and tacit forms of J

style guidelines

Most of the J code presented in the RC J examples are considered good form - to J programmers. The main issue is that programmers familiar with other languages tend to expect an algorithm statement to have explicit iteration, and perhaps consume several lines of code. What is "good form" to a J programmer isn't necessarily easily readable to programmers familiar with scalar languages.

I agree with Donal Fellows in his comments http://rosettacode.org/wiki/User_talk:Dkf#Your_discussion_about_J in that more detailed comments and algorithm explanations are required for every code example in the RC forum, since the whole point is to help readers unfamiliar with that specific language understand what is going on in the code. The more unconventional a language is, the more explanation required. Hence, J examples in RC should display good coding practices (for J) in the example, but that code example should also be accompanied with thorough explanations and comments, all of which should be more thorough than if the audience was just J programmers. For that matter, this advice should be applied for all RC code examples. Teledon 8:47am 13 October 2009

This is great advice! Would it help to have something like an {Obscure} template readers could use to tag examples which they find difficult to understand? --IanOsgood 17:10, 14 October 2009 (UTC)

I personally prefer that the code be lean and have "standard" comments (i.e. have the comments it would have "in real life"). I don't want Task pages to become collections of book reports. I want RCers to compare code, not prose¹.

If the author feels the code deserves deeper consideration, he can post an explanation or exegesis in the talk page or a subpage, and link to it from the solution. See, for example, the explanations for the J zig zag and spiral solutions.

On the flip side, if a RC peruser comes across a solution he finds obscure or confusing, he can request clarification on the Talk page, or on the author's discussion page. That's the purpose of those pages. This might entice the author to post a minor clarification, or inspire him to compose a full exegesis, as above. But I do not agree with the concept of a "{obscure}" tag, as I imagine it would be wielded more as a slur rather than a request for aid.

Regarding how all this applies to J: J's syntax is completely different from the von Neumann approach, and so "fully explaining" a solution amounts to teaching J (its rhematics, syntax, and the semantics of every symbol used -- basically the entire Dictionary). Commenting every J solution "enough" to allow another programmer to implement it in another language would turn J "solutions" into J "essays". We'd basically end up describing the algorithm in English, which defeats the purpose of describing it in J.

So I've concluded the best approach is shock. That seeing that it is even possible to express, in ~50 characters, an algorithm that takes other languages several paragraphs, will sufficiently impress a peruser to investigate J, if only for the opportunity to call bullshit. Especially if it happens in algorithm after algorithm after algorithm ....

¹Except in the case where a Task highlights an aspect of syntax or a language feature, which is best demonstrated, then described in English, e.g. exponentiation operator.

I agree with much of what you say - particularly that full descriptions/explanations of the code don't belong on the main task page. However I do think that a slight increase in the verbosity and amount of comments will help decrease the perceived impenetrability of "standard" J solutions.

Using the Zig Zag task as an example, I think something like one of the solutions in your excellent explanation on the Talk page would be both intriguing and more likely to encourage further study by non-J users, than the current solutions. i.e.

<lang j>

  zigzag=: $ [: /:@; [: <@|.`</. i.

</lang>

vs.

<lang j>

  reorder   =: /:@;
  antidiags =: <@|.`</.

  zigzag=: $ [: reorder [: antidiags i.

</lang>

--Tikkanz 22:46, 14 October 2009 (UTC)

The Select task is perhaps a better example. Compare the current solution:

<lang j> load 'misc' select=: ({::~ 'choose a number 0..' 0&".@prompt@, ': ',~ ":@<:@# [ i.@# smoutput@,&":&> ' '&,&.>) :: (select@([ smoutput bind 'please choose a valid number')) </lang>

to a slightly more verbose one:

<lang j> load 'misc' displayMenu =: i.@# smoutput@,&":&> ' '&,&.> makeMsg =: 'Choose a number 0..' , ': ',~ ":@<:@# displayBadNumMsg =: [ smoutput bind 'Please choose a valid number!'

select=: ({::~ _&".@prompt@(makeMsg [ displayMenu)) :: ($:@displayBadNumMsg) </lang>

As a relatively fluent tacit J user, the first version took a little while to come to grips with if for no other reason than because it was so long. --Tikkanz 02:02, 16 October 2009 (UTC)

---

Thanks to to both of you. I'm going to write up my own views in the next couple of days, and start recommending specific guidlines. Feel free to change them and push them in any direction you see fit. If I get time, I'll try to collect here the views that others expressed in the corresponding J forum thread.

--DanBron 16:55, 14 October 2009 (UTC)

suggested format & style

We have several nebulous purposes on this site, but IMO the primary one is advocacy. So here are my thoughts on a style:

In order that J garner notice and perhaps converts, the J code should differentiate itself. One way to do this is to consistently keep the code short, to pique interest and preclude TL;DR. However, the code should not be so dense as to be impenetrable, to preclude sentiments like these; at the very least the names should provide some hints.

Another way to do differentiate J is to emphasize its unusual or powerful aspects. This includes:

1. Preferring tacit code to explicit,
2. focusing on function composition and powerful and unusual primitives, such as &. and ^:, and
3. minimizing explicit control structures while highlighting tacit flow control (see an exposition on this topic).
   This latter rule isn't hard-and-fast, e.g. if. statements are ok if the code is already explicit, but I would like to see Jers avoid explicit loops at any reasonable cost.

And my idea for a format:

J

---

If I'm reusing names from other tasks or the J wiki, I will directly link to them here. Otherwise there will be no lede or introduction.

Solution:<lang j>name =: a succinct but legible definition NB. Possibly references other defined names,

                                           NB.  as Tikkanz showed, where each name encapsulates a single,
                                           NB.  but powerful thought.  No trivial names.</lang>

Example: <lang j>name argument NB. Example usages; exercise all the interesting aspects,

                 NB.  particularly "free" extensions and generalizations 
                 NB.  which are unavailable in the other languages.</lang>

Discussion: Very brief, high-level overview of how the solution works (e.g. mentions the heart of the solution is a built-in J primitive), with an optional embedded link to a fuller explanation or exposition on the Talk: page.

---

I think this format has several advantages:

1. It gets straight to the point (the solution).
2. It does not conflate the code that defines the solution, the code that invokes it, or its output. This will give non-Jers a more accurate sense of the actual amount of code required to solve the task. I'm thinking maybe "non-core" code that formats the result (as opposed to calculating the result) can also be included in the "Example" section (unless the challenge of the task is formatting, of course). See Pascal's Triangle for an example of how these concepts are separated.
3. At the end, it gives a high-level description for anyone who was baffled by J's spelling scheme or grammar (which description should whet the appetite of the curious to read the full exposition, if there is one). Please follow the talk page link for my thoughts on how to craft a J exposition.

Once we settle on a template, it should definitely be used for new solutions, and it would be nice to back-port it to existing solutions when we have the time (on an ad-hoc basis is fine).

Thoughts? --DanBron 18:54, 10 December 2009 (UTC)

My priorities seem to be: 1. working code, 2. simplicity, 3. ease of description. But, of course, I do not always get everything right on my first try. Rdm 19:15, 10 December 2009 (UTC)