========
Duane,

Thanks for asking.  ICAD style has been hottly debated about every two years
for the last 10+ years.

ICAD Defparts have their own needs that are not reflective of general lisp
usage.
In particular, a defpart has multiple sections for each attribute
and in a normal clos program, each of those attributes would have been a
separate
top-level function.

I've attached a short style guide that I've written for our internal use.
It reflects the basic style I've been using for a while.
At one point I tried to get something like this into our class or
documentation
but it was too controversial.

- Stanley

------=_NextPart_000_0008_01BF97DF.603B6670
Content-Type: application/octet-stream;
        name="style-guide.text"
Content-Transfer-Encoding: 7bit
Content-Disposition: attachment;
        filename="style-guide.text"

ICAD defpart coding style suggestions

3/27/2000 Stanley Knutson

The goal is to enhance readability for large defparts
and to enable grep to find the DEFINITION of a method.

Example:

(defpart my-application (basic-application
                         base-spec-sheet-mixin
                         )
  :part-documentation
  (:description
   "Why this part is useful"

   :examples
   "This shows how to use it:
<pre>
    lisp code
</pre>
"
   )

  :inputs
  (
   :remark "child-object is required"
   :CHILD-OBJECT
   )
  ;; --------------------------------------------------
  :attributes
  (
   :remark ":fancy-width uses the child to center something else"
   :FANCY-WIDTH
   (if (the :foo)
       (if (the :bar)
           (progn
             (do-some-operation
                 with arguments)
             ))
     ;; else (not (the :foo))
     (progn
       (do something else
         )))

   ;; the :%%internal-width is an intermediate
   ;; use ;; (not :remark) since it is not in the generated documentation
   :INTERNAL-WIDTH
   (+ (the :child-object :width) 30)
   )

  ;; --------------------------------------------------
  :pseudo-parts
  (
   (:MY-CHILD
    :remark "Tell why my-child is useful.
This is given as a remark for the :type, that is how the
doc generator wants it."
    :type my-child)
   )
  ;; --------------------------------------------------
  :methods
  (
   (:INITIALIZE-OUTPUT
    (stream)
    :remark "This method writes the first bit
to the output file"
    (write-string "hi there" stream))

   ))

RULES:

1) CAPITALIZE the attribute, method and part names.
It makes them a bit easier to find,
and you can then grep for the capitalized names to find
the locations that define it.

2) Put a comment for almost evey attribute, part or method.
Use :remark if the comment should appear in the generated
reference documentation for this defpart.

3) Put a blank line between each defpart and attribute

4) The closing ) for each section of the defpart
is on a separate line,makes it easier to insert more stuff.

5) Separate the sections with ;;------ lines

6) Put the sections in this order usually:
inputs
optional-inputs
defaulted-inputs
modifiable-optional-inputs
modifiable-defaulted-inputs
modifiable-attributes
attributes
uncached-attributes
combination-attributes
parts
pseudo-parts
methods

7) the very end of the defpart can have the )) to close the last
section and the defpart on the same line.

8) Indent as per emacs ctrl-meta-q WITH THE ICAD INDENT RULES
we customize the Franz-lisp indentation rules to know about defparts.
(the lisp function is fi:indent-sexp)

9) You can group multiple closing )) on one line
but if the block is more than 5 or so lines,
add a ;; comment indicating what block is being closed.
{NOTE: exception rules #4 and #7}

10) name internal methods and defparts with %% so they don't
show up in the documentation or in the ICAD inspector by default.

11) Put one "logical unit" in a file: this usually means
just one defpart per file, with the file name the same as the defpart
name.

The exception is a set of several small closly-related functions.
In this case, they can be grouped into one file.
However, try to keep the file size under 500 lines.  
If it is much bigger than that, you've probably got more than one
group of stuff in the same file, so it merits separation
into different bits.

12) Whenever possible, group the strings that customers will
want to customized into one file of defparameters.
In particular, *think* about what the customer might want to customize.
This will make it easier to document.
In many cases (icad browser for example), we actually ship this
file as part of the reference/example documentation.

As of R7.1, we now have a 'resource string' object
and each major module of ICAD should use that as much as possible
since it allows easier customization on a per-language basis
at runtime.

------=_NextPart_000_0008_01BF97DF.603B6670--

user(1): (pprint '(defun build-upward-closures ()
  (loop for k from *maxplay* downto 0 do
    (setf (aref *upward-closures* k)
          (let ((result (ash 1 k)))
            (loop for i from 0 below *n* do
              (let ((k1 (logior k (ash 1 i))))
                (when (> k1 k)
                  (setf result (logior result (aref *upward-closures* k1)))
                )
              )
            )
            result
          )
    )
  )))

(defun build-upward-closures ()
  (loop for k from *maxplay* downto 0 do
        (setf (aref *upward-closures* k)
              (let ((result (ash 1 k)))
                (loop for i from 0 below *n* do
                      (let ((k1 (logior k (ash 1 i))))
                        (when (> k1 k)
                          (setf result
                                (logior result
                                        (aref *upward-closures* k1))))))
                result))))
user(2):

In general, any lisp code that can be manipulated as data is
easier to work with if it matches the result of its pretty-printed
output.  Now it is true that the pretty printer can be customized,
and thus you're not going to get exactly the same output if you
change, say, indentation rules and other attributes.  But for all of
its customizability, I know of no way to tell the pretty-printer to
dangle its closing parens.  Was this an oversight, or by design?

For Anthony Cartmell, I don't know IDL, and I've already posted
the opinion of an ICAD developer, but it seems to me that whether
or not IDL rules should allow for dangling parens should be weighed
heavily on whether or not a defpart is source-only, or whether it
is possible by any means to get hooks into the source (by way of
a code-walker, macroexpansion, or other debugging activity).  If
the former, then it doesn't matter.  If the latter, then unless
there have been extensions to ICAD's pretty-printer over CL's
printer, the intermediate forms will look "wrong", because they
will have no dangling parens.

The first part of #1 has to do with de-facto standards.  It is
perhaps interesting that almost every lisp programmer disagrees
on something about what lisp should be and do, especially when
dealing with style.  However, it is precisely this tendency to
disagree that makes it so blatanttly obvious when we almost
entirely agree on the issue of dangling parens.

The last part of #1 has to do with screen real estate.  Serious
question: Do you print out your lisp code on paper in order to
look at it?  Or do you have a portrait terminal instead?  Rules
of thumb in any language usually say that you shouldn't have much
more than a pagefull per function, so the question pertains to
your style of viewing code.

#2 looks more like what was said about parens giving no useful
information.  I once read some assembler code from a newbie
programmer that had learned in school that comments must be
used as much as possible.  I don't remember the architecture
that was used, but the code was unreadable because of the
clutter, e.g.

  mov count,r10  ; Move count into register R10
  add 1,r10,r10  ; Increment r10 by 1
  b L4           ; Branch to L4

This programmer's code was full of useful comments like this...

A paren, useful to a compiler should be ignorable to a programmer,
just like a comment line, (sometimes) useful to a programmer,
should be made ignorable by a compiler.  If you fail to add whatever
syntax is required to make a comment invisible to the compiler, the
compiler will barf, because it mistakes the comment for real code.
And if you fail to make parens invisible to the programmers, the
programmers barf, because they are mistaking the parens for real
code.

I will ignore your #3 and #4, and replace them with:

 3) As I posted earlier in this thread, it is the strong opinion
of the lisp that right parens should not dangle.  Just try to get
the lisp printer to print lisp forms with dangling parens; even
setting *print-right-margin* to 1 doesn't help...

 4) Whenever I see lisp code for review, I look for both algorithmic
and/or implementational bugs based on what I see in the code.  One
of the tools I use is to assess the programming level of the programmer
submitting the code.  It involves many factors, most of which are
probably subliminal.  But having thought about it for a day or so,
I can say that whenever I see dangling parens, it contributes to
one of two assessments: "newbie" or "careless".  Note that careless
can apply to me as well; I sometimes see code that I have written
previously which is sloppily formatted, and it is the assessment I
give myself as I correct it.

Heh, heh, including my own!

Once we've decided that dangling close parens are
1) Good for long shallow lists, to allow easy insertion of items, and
2) Bad for short deep lists, because they take up too much space and don't
provide any benefit,
the required rules for ICAD seem obvious to me.  There is some tweaking
possible of course, but the statement that "dangling parens are bad" really
doesn't apply to ICAD code.

I've put together some layout examples of some typical ICAD code for anyone
interested at
http://ourworld.compuserve.com/homepages/AJCartmell/icadparens.html .

Thanks for your comments!

ICAD is really an fairly object-oriented language that just happens to be
based on Lisp.  The basic structure of the code is proprietry, and it could
be implemented in any base language.  The only places Lisp appears are in
expressions and function definitions.

An interesting angle on the discussion, thanks!

(defun build-upward-closures nil
  (loop for k from *maxplay* downto 0 do
    (setf (aref *upward-closures* k)
      (let ((result (ash 1 k)))
        (loop for i from 0 below *n* do
          (let ((k1 (logior k (ash 1 i))))
            (when (> k1 k)
              (setf result (logior result (aref *upward-closures* k1)))
        ) ) )
        result
) ) ) )

Ie, rparens are either on the same line as their
corresponding lparen, or they are clumped together on a
line of their own, where they line up (column-wise)
with an lparen above them.  But if you look closer, you
will realize with a jolt that the lparen that an rparen
lines up with is _not_ its matching lparen...  I guess
the rparens don't quite "disappear" as previous
articles advised, but they do fade into a
quantum-mechanical interchangeability, losing the
identity that we give to the more substantial parts of
the code.

(
  (
    (
) ) )

[I said:]

(defstruct person
    name     ; a string
    address ; the person's street address
    gender ; the symbol 'male or 'female if known, nil of otherwise
)

Otherwise, where does the paren go?  Before the comment?
Inconsistent.  Also, if you want to add a field, you just hop
to the end of the last field line, hit crtl-J and type away ( emacs ).
Often while editing and dubugging a function I'll leave naked
parens, then tighten them back in when I know it's perfect.

"Fernando D. Mato Mira" wrote:

if ( b ) {
  foo()
 } else {
    bar();

I'm in!  I'm in!  I'll be against K&R style.

The above is parodic in nature.  You can still make out quite well
what it means with no punctuation, partially because of the many
levels of redundancy in spoken language.  While lisp code:

defmethod play-move ttt tic-tac-toe move
  let board board ttt setf square board move  if = to-move ttt 1 'x 'o won? ttt
move switch-players ttt

Is unacceptable.  You don't know if it's a specialized function or not, and if
so, on what,
you don't know what the parameters of the function are, etc.

Yes, editors can help you naviagte through code.  But it is nuch more work to
navigate through code then format it so the eye can see it naturally, especially

when code is complex and under heavy development.

* Pierre R. Mai
| It turned out that this functionality belongs in the editor, and not the
| language.  That's why ] will close all outstanding parentheses in many
| Lisp modes.  This way you get the benefits, without the trouble.  ...

  for what it's worth, I have found it significantly easier to write code
  in Emacs with M-( and M-) rather than ( and ).  I guess I picked up that
  habit when I wrote an SGML-mode that automatized the matching between
  start- and end-tags and inserted every character of the element name in
  _both_ the start- and the end-tag.  I generalized this to let, e.g., M-*
  produce ** with the cursor between them, and applied it to "", `', {},
  [], <>, «», ¡!, ¿?, and for that old Common Lisp reader, ||, as well as
  comments with #||#.  in my view, it's a serious mistake to use paired
  delimiters of any kind in a language without _actively_ supporting their
  paired entry when writing.

  well, this gets a little complicated.  the indentation is automatically
  produced for you based on the list structure by the editor.  the list
  structure, however, becomes visually apparent to us humans through
  indentation.  new Lispers look at the list structure and think they
  understand the indentation.  old Lispers look at the indentation and
  understand the list structure.  new Lispers count parentheses and swear.
  old Lispers reindent their code and immediately spot mistakes and just
  clean them up.  the whole Lisp enlightenment experience is about making a
  fundamental swap between syntax and indentation.  (at least one language
  has made this switch permanent: python.  I'm not sure this is a good
  thing.)

| If the parens were based on the indentation then we wouldn't even need to
| use them.

  this is very naive.  _some_ redundancy is a fundamental characteristic of
  _all_ successful communication, between computers as well as humans.

| My whole reason for using dangling parens in my code is to show which
| open-paren each close-paren closes by its indentation.  I don't
| understand why this is such a bad layout style.

  that's because you have never let yourself get immersed in indentation.
  you don't need to see the parentheses.  (if you start seeing fnords,
  alert your local illuminati.)

  I like this argument.  I think we can sum it up like this:

    there is no whitespace after an opening parenthesis.
    there is no whitespace before a closing parenthesis.
    this is the law.  if you break it, it is not pretty.

  someone recently said (sorry, I have been skimming news lately) that he
  had a problem starting with Lisp because everything was in uppercase --
  small things like that can effectively block one's entry into new areas.
  back when I was fairly new to Lisp (eons and eons ago, of course), I came
  across CLISP and its unf<beep>ingbelievably braindamaged pretty printer.
  it was immediately obvious that this had been implemented in a vacuum,
  free from influence from all knowledgable programmers on the planet and
  beyond, and it still sucked.  to see code printed like this was such a
  horrible experience I immediately seized upon the source code to try to
  find out how to turn this gut-wrenching abomination off.  but what did I
  find?  the entire source code was formatted like this!  aaaaauuugh!  and
  everything in German, to boot.  the abyss was staring back at me.  <fade>

  CLISP has since improved.  no animals have been hurt in its production.

* Anthony Cartmell
| Seems to me that this really is the main reason...  is the Lisp layout
| "standard" really this sad?

  there is another, deeper reason behind this that you may have overlooked.

  in C, parentheses are used for a number of fundamentally different tasks,
  and in C++ it gets _completely_ insane, but that's another matter.  after
  a student of C has learned the painful precedence rules by rote and is
  still trying to internalize them so he can just _read_ expressions, the
  parentheses enter the picture as a source of pain or a painkiller when
  the precedence rules do not match the requirements of the expression.
  either way, there is pain.  you will often find C programmers battle
  their operators and their precedence rules for hours on end, recompiling
  frequently because they don't have an interactive environment, either.
  the lesson learned by that vestige of primitive brain that keeps us from
  sticking a hand into hot water the second time, is that parentheses are
  painful.  that a C programmer could have gotten rid of the pain by using
  parentheses consistently around his operators and arguments is lost by
  this primitive part of the brain.

  then Lisp comes around and it's all parentheses.  primitive brain shrieks.

  this is probably not restricted to C, but a property of that horrible
  mathematical infix syntax that is supposedly "natural" and which _also_
  has precedence rules in which parentheses play an important role,
  including the implied multiplication in the absence of operators.  it
  could be that early childhood experiences with the utter mindlessness of
  infix syntax and the need for parentheses to escape out of the stupid
  rules they made up is actually exceptionally traumatic on young brains
  who try to trust their ability to understand the world around them.
  parentheses break their trust, so when they see Lisp and it's all
  parentheses, they become psychotic.  this would explain a lot.  a LOT!

  however, the parentheses in Lisp are just like the semicolon in C.

  here's an experiment you can conduct at home: take a piece of C code to
  which a large group of people have contributed, several thousand lines of
  Open Source should do, modify it slightly in some useful and non-trivial
  way that people would probably like, and insert a newline before every
  semicolon and indent the line an extra tab relative to the line it used
  to belong to, ship the code to all the people who have contributed and be
  very enthusiastic about your improvements, but don't comment on the style
  change.  if you do _not_ receive realistic death threats, consider the
  experiment a failure.

  watch this code die a horrible flaming death:

(foo a                          ; mumble
     b                          ; frotz
     c                          ; fnord
     )

I have one co-worker who has been programming in various languages for
quite a number of years who has a few such "bad habits" that make him
something a liability despite having extensive "experience."

It's that if you're using a text editor that provides *any* support
for paren matching (just about anything better than MSFT WordPad), or
one that provides indentation support (e.g. - like Emacs), then
there's no *value* to having the parens dangle.

And if it's not really buying you anything, then the cost of having
less on the screen is a real cost, and *THAT* is the Bad Thing.

Because screen space is *always* at a premium, regardless of how big
the screen is.  

"NEVER, NEVER, NEVER dangle a _single_ parentheses"

Even in VI it's easy to add an additional last form:
A <backspace> <enter> <hold space bar>

[I'm sure some vihead will have some better way to do the same]

--
Fernando D. Mato Mira
Real-Time SW Eng & Networking
Advanced Systems Engineering Division
CSEM
Jaquet-Droz 1                   email: matomira AT acm DOT org
CH-2007 Neuchatel                 tel:       +41 (32) 720-5157
Switzerland                       FAX:       +41 (32) 720-5720