MC
API
Subsystem
List
Top
Level

Coding Standards for QA Partner Code

  1. Symbolic Names
    1. Classes and Types
    2. Constants
    3. Exception Codes
    4. Enum Values
    5. Variables
      1. Global Variables
      2. File Scope (Private) Variables
      3. Local Variables and Instance Variables
    6. Windows
      1. Main SubSystem Windows
      2. Global Windows
      3. File Scope (Private) Windows
      4. Child Windows within Other Windows
      5. Local Windows
    7. Subroutines
      1. Global Subroutines
      2. File Scope (Private) Subroutines
      3. Public Methods
      4. Private Methods
      5. Testcases
    8. SubSystem IDs
    9. Type Abbreviations
  2. Assorted Coding Guidelines
    1. Exceptions
      1. Exception Constants
      2. Raising Exceptions
    2. Window Declarations
      1. Windows vs. Window Classes
      2. Global Window Usage
  3. Files
    1. QAP Source Files
      1. Test Script (*.t) Files
      2. SubSysDefs.inc
      3. Class Files
      4. SubSysTestcases.inc
      5. SubSysUtils.inc
    2. HTML File Names
  4. Inline Documentation
    1. Subroutine Headers

Symbolic Names

This section describes guidelines for choosing symbolic names in QA Partner code.

Classes and Types

Syntax: <SUBSYS> <someName> ['Dlog']

Append "Dlog" for dialog box classes. The main window class for each subsystem should be called "window" with the subsystem prefix.

Examples: BINwindow, MCtimeCode, EDLdiskType, BINopenDlog

Constants

Syntax: <type> <SUBSYS> '_' <SOME_NAME>

Examples: iDG_TIMEOUT, sMC_PROJECT_PATH

Exception Codes

Syntax: 'X_' <SUBSYS> '_' <SOME_NAME>

Examples: X_MC_SOMETHING_WENT_WRONG, X_BIN_FILE_NOT_FOUND

Enum Values

Syntax: 'e' <SUBSYS> '_' <SOME_NAME>

Examples: type MCtcType is enum { eMC_TC_DROP, eMC_TC_NON_DROP };

Variables

Global Variables

Syntax: 'g' <type> <SUBSYS> <someName>

Examples: giMCkludgyGlobalInteger, glwMCbaseState

File Scope (Private) Variables

Syntax: '_' <type> <SUBSYS> <someName>

Examples: _sCLtitle, _iEDLcounter

Local Variables and Instance Variables

Syntax: <type> <SomeName>

Examples: lwCheckboxes, sUserName

Windows

Main SubSystem Windows

Syntax: 'gw' <SUBSYS> 'window'

Examples: gwPRJwindow, gwCONwindow

Global Windows

Syntax: 'gw' <SUBSYS> <someName> ['Dlog']

Append "Dlog" to dialog boxes.

Examples: gwPRJopenDlog

File Scope (Private) Windows

Syntax: '_w' <SUBSYS> <someName> ['Dlog']

Append "Dlog" to dialog boxes.

Examples: _wMCtempWin, _wBINsillyDlog

Child Windows within Other Windows

Syntax: <SomeName>

Note: in general, do not encode the gadget type in the name. For example, use "FarbleOption", not "FarbleOptionCheckBox". This rule can be broken when there are two different UI controls for the same logical parameter, such as "LevelSlider" and "LevelText".

Examples: gwPRJconfirmDlog.Cancel, gwPRJconfirmDlog.OK

Local Windows

Syntax: 'w' <SomeName>

Examples: wCheckbox, wFirstButton

Subroutines

Global Subroutines

Syntax: <SUBSYS> <someName>

Examples: MCverifyNotBogus(), EDLejectDisk()

File Scope (Private) Subroutines

Syntax: '_' <SUBSYS> <someName>

Examples: _BINshuffle()

Public Methods

Syntax: <SomeName>

Examples: wMyWindow.DrawCurtains()

Private Methods

Syntax: '_' <SomeName>

Examples: this._GetPaneID()

Testcases

Syntax: 'tc' <SUBSYS> <someName>

Examples: tcBINloadClip(), tcPRJopenBin()

SubSystem IDs
AA Auto Assembly
AC COMPANYCode
AM Audio Mix Window
AP Audio Punch-In
AT COMPANYTalk
AU Audio Tool
BE Bin Export
BI Bin Import
BIN Bins
CAL Calculator
CHL Change List Tool
CL Cut List Tool
CM Composer Window (MC/FC)
CME Composer Window - Effect Mode
CMT Composer Window - Trim Mode
CMX Composer Window (MCX)
CON Console
CP Command Palette
CPR Compression Window
CRD Consolidate/Relink/Decompose
DBG Debug Window
DC Digital Cut
DG Digitize
DK Deck Controller
EC Edgecode Utils
EDL EDL Manager
EQ Audio EQ Window
FXP Effect Palette
FXR Effects - Rendering
HW Hardware Tool
LOC Locators
MC PRODUCT (shared stuff)
MT Media Tool
PL Player
PM Popup Monitors
PRJ Project Window
REC Recovery System
SET Settings Window
SP Serial Ports
TL Timeline
TC Timecode Utils
TT Title Tool
UI UI Shell ???
VI Video Input Window
VO Video Output Window

Type Abbreviations

Syntax: ['l' | 'a']... <1st char of base type>

'l' and 'a' before the base type mean "list of" and "array of" respectively.

Base Types

Assorted Coding Guidelines

Exceptions

Exception Constants

Each exception has its own constant whose value is a 5-digit decimal integer. The high-order two digits identify the sub-system, the low-order three digits are assigned sequentially within the subsystem, starting with 001.

Note: QA Partner exception codes are, apparently, all negative.

Sub-system codes are defined in MCglobal.inc, per the following example: 

const integer X_MC  = 00000;
const integer X_BIN = 01000;
const integer X_PRJ = 02000;
Exception codes are defined in the SubSystemDefs.inc file, per the following example: 
const integer X_BIN_FILE_NOT_FOUND   = X_BIN + 001;
const integer X_BIN_FOLDER_NOT_FOUND = X_BIN + 002;
const integer X_BIN_YOU_MESSED_UP    = X_BIN + 003;

Raising Exceptions

When an exception is raised, the first argument to the raise operator is the exception constant, and the second argument is a descriptive string. The string is to benefit the user; the exception constant is to allow the code to catch, test for, and process the exception.

Window Declarations

Windows vs. Window Classes

In general, window classes should be used to define a window, rather than defining the window in a window instance. In other words, define the contents, instance variables, and methods of the window using "winclass", not "window". Dialog boxes are the main exception to this rule.

Global Window Usage

Global windows should be used only if there can never be more than one simultaneous instance of that window, and if the contents of the window do not change significantly. Otherwise, the window should be dynamically instantiated and returned by a utility routine or by a method of its parent window.

Files

QAP Source Files

Test Script (*.t) Files

These files must be kept as simple as possible. Not necessarily short, but simple. These files will be the ones most often modified by engineers with limited experience with QA Partner and/or our test code. These files must also be heavily commented for the same reason.

SubSysDefs.inc

This file contains all the classes, constants, types, windows, and global variables that belong to the sub-system. If the file grows very large (beyond 5-8 pages), it should be broken up by removing dialogs or large class declarations to their own files.

Class Files

If a class is defined in its own file because of its size, the name of the file should be the same as the class name, plus ".inc".

SubSysTestcases.inc

These files should contain only testcases, and possibly private support routines that are only used by those testcases.

SubSysUtils.inc

If the sub-system requires any utility functions that are not class methods, they should be defined here.

HTML File Names

Subsystem overview
or entire subsystem: 		<SUBSYS> "subsys.html"
One class: <ClassName> ".html"
Many classes: <SUBSYS> "classes.html"
Many windows: <SUBSYS> "winDefs.html"
Many testcases: <SUBSYS> "testcases.html"
Many utilities: <SUBSYS> "utils.html"

Inline Documentation

Inline Documentation

Inline documentation consists of comments appearing within the QA Partner Source code itself. It should be used whenever possible for clarity and readability.

Subroutine Headers

//==============================================================================
//	Description of what the subroutine does

integer		// description of return value
    MCfooBar(
        integer iArg1, 	// description of arg1
        out list of string lsArg2	)	// description of arg2
{
...
}

This page is maintained by (REMOVED).
It was last updated 24 March 2000.