Some time ago, I made a number of suggestions for code layout that parallel
some of
those in this discussion. Two that are relevant to the example here are:
1 ) precede the definition with an explanation of what the code is supposed
to do using
the convention "NB.* <name>: " - this is done in some of the code supplied
with J.
2) end the definition with a simple usage example using the convention "
NB.EG"
I was going to use the the example being worked on in this thread to
illustrate a couple
of other ideas but I can't figure out
1) what the code is supposed to do, and
2) how to use the function with an argument that gives me something other
than the input as a result.
which actually illustrates why the two conventions are a good idea. So, I
will use some code
I do understand to illustrate these and a couple of other conventions I like
to follow.
NB.* partitionByValue: given values on which to partition and vector of
numbers
NB. to partition, return partitioned indexes into vector.
partitionByValue=: 3 : 0
'brkvals vals'=. y. NB. Break values are partition limits.
gv=. /: brkvals,vals
ptn=. 1,}:gv e. i.#brkvals
pv=. ptn <;.1 gv NB. Partition the indexes.
pv=. pv-.&.><i.#brkvals NB. Drop break indexes from partitioned
indexes.
pv=. pv-&.>#brkvals NB. Adjust for leading brkvals.
NB.EG pv=. partitionByValue (i. 3);0.5*i:5
NB. pv{&.><0.5*i:5
NB. +--------------------+-----+-----+-----+
NB. |_2.5 _2 _1.5 _1 _0.5|0 0.5|1 1.5|2 2.5|
NB. +--------------------+-----+-----+-----+
NB. values less than 0, from 0 -1, 1-2, 2 and above.
)
So, the special comment "NB.* <name>:" precedes the definition to explain
what the function is
supposed to do. I used to put this explanation in the body of the function
but, at the
suggestion of Chris Burke, moved it out to precede the definition - either
way seems
fine to me so I took his suggestion simply because he's written a lot of the
J code in
the system and a convention works better if there's only one of them.
This "NB.* <name>:" convention is handy too if I've written a lot of
definitions in a single file
because I can pull all of them and start the file with a comment block
listing all its
functions as a table of contents. This means the explanations are
duplicated but
it seems like a small, useful bit of overhead for any sizeable file of
functions.
In this example, I went a bit overboard with the trailing comment. Usually,
I just
end the definition with a valid, preferably common, usage example. It's
handy to put
this at the end so that, if I type in the function name, the line ending up
the closest to
my cursor is one I might like to grab and modify.
As far as indenting, it seems more readable to me to indent the body - I use
three spaces
initially because this is what the interactive J session uses and I often
build a function by
editing code from the session. Subsequent indenting is four spaces because
this seems
like enough to separate blocks visually but not so much as to make lines too
long. I wouldn't
mind some other small number like two or three for the indentation amount.
I don't care that
the first indent is not consistent with following ones. Also, I use spaces
instead of tabs because
my emacs editor shows tab as a little "HT" glyph.
Comments to the right of the line works for me. I try to line them up for
related blocks; failing
this, I align them on multiples of five because this looks neater. I'll
occasionally use irregular
alignment if the code part of the line is nicer longer. Sometimes, I'll
insert a full line comment
if it's too long to take up only half a line.
One last thing: is it really too hard to use even slightly meaningful
names? In the example above,
I use short but somewhat meaningful names. I fail to understand the
disrespect a writer shows
to a reader by using deliberately meaningless names like "foo".
Single-letter names as well
seem to save very little but make searching and replacing significantly more
onerous.
I dislike long names as much as most people on this forum probably do,
especially inside
a definition but tend to be a little verbose for external names (which will
probably occur infrequently
as well, thus mitigating their length).
That's my 2 cents.
On 10/28/06, bill lam <[EMAIL PROTECTED]> wrote:
Oleg Kobchenko wrote:
> Possbibly, writers using different code layout conventions
> had their reasons. It would be good to hear them.
...
--
Devon McCormick
^me^ at acm.
org is my
preferred e-mail
----------------------------------------------------------------------
For information about J forums see http://www.jsoftware.com/forums.htm
