========
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--