Anonymous user
J/HouseStyle: Difference between revisions
→style guidelines: no {obscure} tag & general thoughts
(→style guidelines: suggestion: {Obscure} template) |
(→style guidelines: no {obscure} tag & general thoughts) |
||
Line 23:
: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? --[[User:IanOsgood|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<sup>[[#1|1]]</sup>.
::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 [[Talk:Zig_Zag#reading_the_J_examples|zig zag]] and [[Talk:Spiral#J|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 epithet 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 ....
::<div id="1"><sup>1</sup>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#J|exponentiation operator]].</div>
----
| |||