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>

  reshape=: $
  reorder=: /:@;
  antidiags=: <@|.`</.
  integers=: i.
  zigzag=: reshape [: reorder [: antidiags integers

</lang>

or perhaps:

<lang j>

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

</lang>

--Tikkanz 22:46, 14 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)