Coding Conventions

HWAT Coding Conventions and Function Headers

  1. All lines should be terminated with a semi-colon ";", C-Style.
  2. Namespaces are all lowercase and begin with "::".
  3. Function names use Hungarian notation and start with an uppercase letter.
  4. Variable names use Hungarian notation and start with lowercase letter.
  5. Variable names use following prefixes:
    For Widgets
    Option <Parameter>
    Description
    button
    "btn_"
    canvas
    "cnv_"
    textbox
    "txt_"
    combobox
    "cmb_"
    frame
    "frm_"
    radiobutton
    "rad_"
    checkbox
    "chk_"
    collector
    "col_"
    label
    "lbl_"
    entry
    "ent_"
    scrollbar
    "scr_"
    For Data Types
    Option <Parameter>
    Description
    integer
    "n_"
    float/double
    "d_"
    string
    "str_"
    bool
    "b_"
    array
    "arr_", since it may contain more than one data type

    For list variables: Append "List" to the variable name (n_myIDList).

    For return variables: Use "retval" as the variable name regardless of data type.

  6. All functions will return 1 or any meaningful value for success or partial success, "null" for a program failure (this means the function is writing an error message) i.e. return {}. The function can also return {}. If an API function it calls returns {}, in this case, it does not need to write an error message.
  7. All functions within namespaces must conform to style A, and not style B:
    a.	Namespace eval ::hwat::util {};
    proc ::hwat::utils::MyProc {n_intArg d_floatArg} {
    puts "hello world";
    return 1;
    }
    b.	Namespace eval ::hwat::util {
    proc ::hwat::utils::MyProc {n_intArg d_floatArg} {
    puts "hello world";
    return 1;
    }
    # end namespace
    }
  8. The function ::hwat::utils::WriteErrorMessage will be used to post error messages to the message box.
  9. If the hwat::globals::DEBUG variable is set to 1, the function ::hwat::utils::WriteDebugMessage will be used to post debug messages to the message box. Use ::hwat::utils::SetDebugOnOff to set the debug variable.
  10. The function ::hwat::utils::PostToMessageBox will post messages to the message box in the application or post messages in a Tk message box in HyperMesh.

The following function header must be used with the following rules:

  1. One argument per line.
  2. The LAST person to modify should be first in the Author list.
  3. Everything that begins with "##" and keyword "proc" will be parsed, so begin all other comments with a single "#".
  4. If needed, have a more detailed description for developers after the headers and starting with "#".
  5. If a change is made to the procedure just overwrite the info in the header instead of appending to it.
#######################################################################
## Procedure name: 
## ::vcl::utils::GetXYZFromTag
##
## Description:
## Returns the coordinates of the node with the given tag.
##
## Arguments:
## Tag = Keyword "TAG:" followed by the tag name (ex. "TAG: J_Node"). 
## Poo = some other argument, just to make my point.
## 
## Returns:
## A Tcl list containing the x, y and z coordinates of the node if successful, 
## {} if unsuccessful.
## 
## Comments:
## Where's the beef?
##
## Author: 
## Girish Deshmukh, Shawn Freeman
##
## Last updated:
## 02/28/2003
##
#######################################################################
##
## UAT
## Test Procedure:
## 1. Create Tag on a node in HM
## 2. Verify Tagged nodes X/Y/Z location using HM
## 3. Call this function with the Tag name as the argument
##
## Success:
## Returns the X/Y/Z location of the node which you tagged
## 
## Failure:
## Case 1 – passing in a Tag name that contains a space or other special character
## Result 1 – function cannot find Tagged node and should return {} gracefully
## Case 2 – Tag does not exist in session
## Result 2 - function cannot find Tagged node and should return {} gracefully
##
#######################################################################