From mboxrd@z Thu Jan 1 00:00:00 1970 From: Keith Seitz To: Insight Maling List Subject: [RFC] Rough draft of style guide Date: Thu, 15 Mar 2001 21:04:00 -0000 Message-id: X-SW-Source: 2001-q1/msg00325.html 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".