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
