While re-familiarizing myself with my ASPECT source code & notations, I decided it would be best to define my practices for future reference.
File naming convention
- C- prefix to a filename represents a component source module that is intended to be included in an application. Component source modules are not intended to be compiled on their own. Some component source modules will have a proc main included to demonstrate the usage of the component source. This procedure is almost always excludable using a #define _PROGRAM within the application before including the component source module.
- T- prefix to a filename represents a test module that is intended as a proof of concept or to debug component source modules. Test modules are not intended for distribution.
- O- prefix to a filename represents a recorded module that is intended to capture a process that will later be converted to an application (i.e., capturing the prompts & input used to enter an NPA, then converting that to an application that enters NPAs in to a system sequentially.)
Definition naming convention
- Definitions without prefix are intended to be called as replacement macros for other functions or procedures, or in some cases as formula (e.g., F(x, y, z) as used in my C-MD5 component source project as a formula macro.) This simplifies the coding process at the cost of code readability.
- Definitions with a prefix of a single _ (underscore) are used to define constants or formula. (e.g., _S11 as used in my C-MD5 component source project as a constant)
- Definitions with a prefix of a double __ (underscore) are used to define switches to change source code compile behavior. (e.g., __C_MD5 as used in my C-MD5 component source is used as a switch to ensure that the C-MD5.WAS component source module can only be included in an application once. Subsequent #include attempts will be ignored by the command #ifndef __C_MD5, since the switch has previously been defined all code is ignored until the #endif)
Variable naming conventions
- [g_][i,sz,l,bln][variable name]: e.g., g_szBuffer is a global string called buffer.
- g_ prefix indicates that the variable is a global.
- variable type:
- i prefix indicates that the variable is an integer
- sz prefix indicates a string with a zero termination (all strings are zero terminated in ASPECT scripting)
- l prefix indcates a long (need to research ASPECT again to determine the value of Long vs Integer)
- bln prefix indicates the variable is a boolean (usually an integer that is treated as true/false)
Function naming convention
- Procedures (_p_ and p_) return no value upon completion.
- Functions (_f_ and f_) return a value upon completion.
- Underscore prefixed functions (_p_ and _f_) are intended to be called within a component source module only and should not be called by a function or procedure outside of the component source in which they are defined. This emulates “private” functions within object oriented programming (even though there is no such thing as OOP or private functions within ASPECT). This is done to maximize code portability.
- letter prefixed functions (p_ and f_) are intended to be called within a component source module or by application code. This emulates “public” functions within OOP. This is done to provide a black-box style of coding that allows portalbe code to be built upon component source modules without worrying about how the inner workings of the module performs.