[RFC] Rough draft of style guide

[Keith Seitz <keiths at cygnus dot com>]

Hi,

This is really, really rough. I've only touched on a few things, but you 
get the idea.

Let me state one thing: there is NO coherent style in Insight today. Got 
that? There are four or five different ones: mine, Jim Ingham's, Martin 
Hunt's, and Tom Tromey's. So if I hear someone say, "that goes against 
the current style", well, maybe you'll be close enough to hear me scream. 
:-)

Let us please discuss this, especially the part about naming class 
variables and methods/procs. I think it is only important to 
differentiate between class variables and "locals", therefore I have 
always named non-pubilc class variables with a leading underscore (or an 
uppercase letter :-).
 
I do not (and will not) use public variables. They are evil. (I do use them 
for widget configury, but I do NOT refer to them anywhere but in their
own configbody's. We use ITk, so we should be using itk_options for 
widget/window configury.)

I plan on doing a lot of work on Insight to make it look (and work ;-) 
better, so I want to draw some concensus on this ASAP.

Be gentle!
Keith

Insight Style Guide
-------------------

. Adding new files

When making a new class, FooWin, please name the source files
"foowin.ith" and "foowin.itb". The ".ith" file should contain the
class definition and the ".itb" file should contain only the class
implementation. This will allow developers to reload the
implementation files without having to restart the application.
This is very useful for debugging. You simply add debug statements
in your .ith file, resource the file (using the debug window) and
POOF! Your changes are in.


. Headers and bodies

When writing the class definition files (let us call them "header"
files), please group all variables, methods, and procs of the same
protection level in order from most-exposed to least, i.e., public,
protected, private.

Within these groupings, list variables first, followed by methods and
procedures.

Please do not put any major method or procedure implementation into
the header file. Only trivial things should go here. Just like C++.

Please comment on the use/purpose of class variables in the header
files, but put only a brief description of the purpose/use of
class procs and methods. Save the nitty-gritty for the implementation
file.


. Comments

All comments in the body file for procs an methods should mention the
protection level and function type (method/proc). This way, one
need not consult the header file every three seconds to figure out
who can call what and when.

Method/proc implementation commenets should look start and end with
the comment character, a space, and sixty dashes. Example:

# ------------------------------------------------------------
#  PUBLIC PROC:  public_proc - This is my public proc
#   responsibile for doing something.
# ------------------------------------------------------------

Note the spacing: one space before protection level and two
spaces after (before method/proc name). All subsequent lines
should be indented one character from the topmost line (note
the carats (^) denoting spaces):

#^------------------------------------------------------------
#^^PRIVATE METHOD:^^private_method^-^This^is^my^private
#^^^proc.^It^does^nothing^right^now.
#^------------------------------------------------------------

Please full sentences in these "big picture" comments.


. Variable/Method/Proc Naming Convention

All public procs/methods/variables should be lowercase. Please
precede all protected and private procs/methods/variables with
an underscore. Precede all "common" variables with a "c_".
This will make reading the code so much easier.

Examples:
common c_common_variable {}
public variable public_variable
protected variable _protected variable
private variable _private_variable

public proc public_proc {}
protected method _protected_method {}
private method _private_method {}

This isn't perfect, but it is now (more) obvious what is class
data and what is not. Except for public variables... What to do?
Public variables are evil anyway. Write accessor procs/methods
if you feel you must have them.

The big deal is to distinguish between local variables and
class variables.

. Miscellaneous

Put braces around expressions in control statements, e.g.,
"if {!$error}" not "if !$error" and "expr {$foo+$bar}" not
"expr $foo+$bar".