I agree with flushed tabbed comments being a nice touch. One convention I like is putting usage instructions inside the definition, so that they can be recalled in the ijx window. I often wished there was special parsing in J for a tabbed comment below a tacit definition, so that the comment could be shown (without scrolling sideways) when code is displayed.
----- Original Message ---- From: Oleg Kobchenko <[EMAIL PROTECTED]> To: General forum <[email protected]> Sent: Saturday, October 28, 2006 7:17:59 PM Subject: [Jgeneral] Whitespace and Comments This note is regarding coding conventions, in the area of comments and whitespace treatment regarding J code in general and in the Wiki. It may be possible that people have different abilities of fluently reading code depending on the layout in terms of whitespace and the location of comments. Regarding spaces. In most languages, function body is indented from the signature line: spath_z_=: 3 : 0 if. _1-:z=. 4!:4<'y' do. y return. end. if. '.'~:{.y=. jhostpath y do. c=. 0 else. c=. -('..',PATHSEP_j_) +/@E. y end. p=. ; c }. (<;.2~ =&PATHSEP_j_) jhostpath z{::4!:3'' p , (-c*3) }. y ) However, in many J scripts the body is flush with the margin. As a result, in longer definitions it is hard to see the function boundaries: spath_z_=: 3 : 0 if. _1-:z=. 4!:4<'y' do. y return. end. if. '.'~:{.y=. jhostpath y do. c=. 0 else. c=. -('..',PATHSEP_j_) +/@E. y end. p=. ; c }. (<;.2~ =&PATHSEP_j_) jhostpath z{::4!:3'' p , (-c*3) }. y ) To overcome the problem of function boundaries, the flower box style separators are used: NB. ========================================================= So it's not clear, what really the absence of body indent is saving? Even if it is the parsing time inside the body that is saved, it far less valuable than the human parsing time when reading the definition. Regarding comments. It is well known that comments can be helpful, as much as they can disrupt the ability to read the code. In particular, when lines of code are interweaved with comment lines. I believe, this works OK, if the writer uses syntax coloring, but then when the code is in Wiki or plain text, or for people with less accute color separation ability, this distinction does not work: spath_z_=: 3 : 0 NB. bail out if not in a script if. _1-:z=. 4!:4<'y' do. y return. end. NB. count upward path elements if. '.'~:{.y=. jhostpath y do. c=. 0 else. c=. -('..',PATHSEP_j_) +/@E. y end. NB. get path and drop upward elements p=. ; c }. (<;.2~ =&PATHSEP_j_) jhostpath z{::4!:3'' p , (-c*3) }. y ) Instead, two position of comments can be considered non-disruptive: aligned in column side-by-side with code; or in a separate comment block: spath_z_=: 3 : 0 if. _1-:z=. 4!:4<'y' do. NB. bail out if not in a script y return. end. if. '.'~:{.y=. jhostpath y do. NB. count upward path elements c=. 0 else. c=. -('..',PATHSEP_j_) +/@E. y end. p=. ; c }. (<;.2~ =&PATHSEP_j_) jhostpath z{::4!:3'' p , (-c*3) }. y NB. get path and drop upward elements ) Or collected in a separate block: NB. spath is calculated so NB. - bail out if not in a script NB. - count upward path elements NB. - get path and drop upward elements Possbibly, writers using different code layout conventions had their reasons. It would be good to hear them. ____________________________________________________________________________________ Get your email and see which of your friends are online - Right on the New Yahoo.com (http://www.yahoo.com/preview) ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
