Anonymous user
J/HouseStyle: Difference between revisions
no edit summary
m (→{{header|J}}) |
imported>Katsumi No edit summary |
||
| (10 intermediate revisions by 4 users not shown) | |||
Line 33:
:::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.
<syntaxhighlight lang="j">
</syntaxhighlight>
</lang>▼
:::vs.
<syntaxhighlight lang="j">
</syntaxhighlight>
</lang>▼
:::--[[User:Tikkanz|Tikkanz]] 22:46, 14 October 2009 (UTC)
:::The [[Select]] task is perhaps a better example. Compare the current solution:
<syntaxhighlight lang="j">
load 'misc'
select=: ({::~ 'choose a number 0..' 0&".@prompt@, ': ',~ ":@<:@# [ i.@# smoutput@,&":&> ' '&,&.>) :: (select@([ smoutput bind 'please choose a valid number'))
</syntaxhighlight>
</lang>▼
::: to a slightly more verbose one:
<syntaxhighlight lang="j">
load 'misc'
displayMenu =: i.@# smoutput@,&":&> ' '&,&.>
Line 58:
select=: ({::~ _&".@prompt@(makeMsg [ displayMenu)) :: ($:@displayBadNumMsg)
</syntaxhighlight>
:::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. --[[User:Tikkanz|Tikkanz]] 02:02, 16 October 2009 (UTC)
Line 72:
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,
Another way to do differentiate J is to emphasize its unusual or powerful aspects. This includes:
:# Preferring tacit code to explicit,
:# focusing on function composition and powerful and unusual primitives, such as <code>&.</code> and <code>^:</code>, and
Line 80 ⟶ 81:
And my idea for a '''''format''''':
===
----
If I'm reusing names from other tasks or the [[j:Essays|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>▼
'''Solution''':
'''Example''': <lang j>name argument NB. Example usages; exercise all the interesting aspects, ▼
<pre>
NB. particularly "free" extensions and generalizations ▼
name =: a succinct but legible definition
NB. which are unavailable in the other languages.</lang>▼
▲
'''Alternative solution (''style'')''':
<pre>
name =: alternative, equivalent solution in a different style
NB. For example, explicit as opposed to tacit. ALWAYS lead with the preferred
NB. (usually shortest) solution; alternative solutions are merely showcases.
NB. Note also that the exact same name is assigned, indicating all solutions
NB. are identical, and could equally be the referent of the Example section.
NB. Do not present too many solutions; keep the J entry short and sweet.
NB. Further solutions can always be linked to.
'''Example''':
<pre>
name argument
'''Discussion''': Very brief, high-level overview of how the solution works (e.g. mentions the heart of the solution is a built-in J <code>primitive</code>), with an optional [[Talk:J/HouseStyle#J|embedded link]] to a fuller explanation or exposition on the Talk: page.
Line 101 ⟶ 123:
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? --[[User:DanBron|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. [[User:Rdm|Rdm]] 19:15, 10 December 2009 (UTC)
:: At this stage in the game, let us focus on concrete suggestions, rather than abstract goals (though you can record your thoughts on that in earlier sections of this page).
::: In re your priorities: Working code is absolutely mandatory; one should not "save page" if the solution does not correctly implement the task as described (and perhaps as clarified by other implementations). Simplicity and ease of description are well intentioned goals but problematic in the context of J on RC (outside the general problem of subjectivity).
::--[[User:DanBron|DanBron]] 19:20, 10 December 2009 (UTC)
: I like the outline for J solutions described above. A significant number of solutions follow this format already. Should there be guidelines for formatting code too?--[[User:Tikkanz|Tikkanz]] 21:29, 10 December 2009 (UTC)
:: Do you have anything particular in mind? I'm pretty relaxed about this. Some fine-grained stylistic rules I personally like to follow:
:::# Ancillary definitions that shouldn't persist in the namespace should be defined locally (<code>=.</code>); main verbs which solve the task or otherwise deserve attention should be defined globally (<tt>=:</tt>). Global names which rely on local names should fix (<code>f.</code>) them.
:::# Space a line of code according to J's rules of binding power (e.g. put verbs directly adjacent to conjunctions, space out trains a little, etc).
:::# Minimize parens. Maximize use of forks (this isn't an endorsement of capped fork, though that does allow certain verbs to scan better).
:::# Control on the left, data on the right. This extends to verb trains in the sense that the more complex tine should be on the right, and <code>~</code> used on the middle tine as required.
:::# For the sake of legibility to others, I will try to eschew tacit adverbs. But I'm addicted, so I can't make any guaruntees.
::I've got a bunch more that don't occur to me immediately. But I'm interested in what you (and others) have to say. As I said, this is not as important to me as "big picture" style and formatting -- I still want to allow individual authors to express their own styles. --[[User:DanBron|DanBron]] 21:51, 10 December 2009 (UTC)
== Meta issue: "converts" ==
Personally, I am slightly bothered by the idea that we are trying to gain "converts".
In part, I think this misses out on some of J's strengths. But, also, I am bothered by the implications.
But, first: when you are working with other people, you need to spend some time using their language. This means that some of the most productive uses of J will probably be multi-lingual uses. I am sure we can all come up with some good examples of this, but Javascript in browsers is probably a fairly common case, this year.
Second, J has some strengths that become stronger when used in the context of developing programs in other languages. In particular, J pushes "control structure issues" into its expressions, and refactoring code -- and re-architecting code -- often winds up being a set of relatively minor changes in a J program. In other words, J can help us reason about program architecture by making experiments easy. If we are working purely in J, this issue is of course important: sometimes we can only gain reasonable performance from a program by re-architecting it to work around issues introduced by the interpreter. However, various other languages make architectural changes difficult and some significant number of projects could benefit from an architectural exploration phase even when the target language is not suitable for that task and yet can not be changed.
Third, historically speaking J evolved from notation which was intended to convey ideas and teach people about computing. J suffers and benefits, of course, from the ugliness and ubiquity of ASCII. Nevertheless, it seems to me that J has some serious potential, for conveying ideas about programs. But I feel this potential gets lost in the noise when we focus on "J as the way to do things" rather than using J to present concepts as clearly as possible. (And I am probably just as guilty of this mistake as anyone else.)
Of course, for some people and for some projects, J is the right tool and I do not want to take anything away from that. And, almost certainly, some projects which do not currently use J could probably benefit greatly if they did. And, sometimes a small bit of J code you can write up in an hour or so might outperform code that takes months or years to write in another language. But I think that if we try and pretend that J should always be the right tool for the job that we diminish both the J community and the other communities we can participate in.
Essentially, when we make J as disposable as we can, we wind up creating situations where people can choose J on its merits rather than because of some other issue.
So, what does this mean for J's House Style? I am not completely sure. But perhaps a good start would be to call out a handful of "decent examples of good presentation of ideas, using J" -- to put some emphasis on the conveying of concepts, where it belong.
--[[User:Rdm|Rdm]] 17:21, 24 May 2010 (UTC)
| |||