[RFC] Rough draft of style guide

[RFC] Rough draft of style guide

[Keith Seitz]

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".

Re: [RFC] Rough draft of style guide

[Tom Tromey]

Keith> There are four or five different ones: mine, Jim Ingham's,
Keith> Martin Hunt's, and Tom Tromey's.

For those who don't know, my coding style has been documented for a
long time:

    http://drip.colorado.edu/~tromey/tcl-style-guide.html

I think I wrote this in 1996 but I don't remember.

Keith> Let us please discuss this, especially the part about naming
Keith> class variables and methods/procs.

I think this is fine as far as it goes.
Some things are missing.

For instance I like to use the noise words like "then" and "else".
However gdbtk seems to typically use "else" but not "then".

There are probably more things like this.  Feel free to raid my style
guide for ideas if you want.

I'd like to see this checked in as gdb/gdbtk/README.STYLE or something
like that.

Tom

Re: [RFC] Rough draft of style guide

[Jeff Holcomb]

On 16 Mar 2001, Tom Tromey wrote:

> I'd like to see this checked in as gdb/gdbtk/README.STYLE or something
> like that.

I agree.  There should be a link to it on the sources.redhat.com site but 
also be checked in to the codebase.

--
Jeff Holcomb
jeffh@redhat.com
GDB Engineering
Red Hat, Inc.

Re: [RFC] Rough draft of style guide

[Jim Ingham]

Keith,

This looks fine so far.  Probably be good to decide on a variable naming 
convention as well, hower (_ or capitols between words) since this is 
not consistent in the Insight tcl sources either.  It is probably 
better, as much as you can, to stick to something like the GNU 
conventions, since this code IS used with gdb...

BTW, I don't agree with Tom about  using "then", he is about the ONLY 
Tcl programmer I know who still uses it, and many don't even know it is 
supported.  It is good to use "else" however.  This makes the if 
constructs look like C, which is the language most people are familiar 
with.

Jim
_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-_-
Jim Ingham                                                           
jingham@apple.com
Developer Tools - gdb