Parameter names are constructed to show the data type of the parameter and to indicate its use:
Where possible, standard names have been used to describe parameters. Where multiple word qualifiers are used, the order of the words is not significant.
For example:
──────────────────────────────────────────────────────────────
hdc /* device context handle */
pszFilename /* pointer to a character string */
──────────────────────────────────────────────────────────────
The following standard base tags and their associated type names are defined:
┌──────────┬──────────┬────────────────────────────────────────┐ │Tag │Data Type │Description │ ├──────────┼──────────┼────────────────────────────────────────┤ │f │BOOL │Flag or Boolean variable. The qualifier │ │ │ │describes the condition associated with │ │ │ │the flag when it is TRUE. For example, │ │ │ │fSuccess is TRUE if successful and FALSE│ │ │ │if not; whereas fError is TRUE if an │ │ │ │error occurred and FALSE if no error │ │ │ │occurred. For objects of type BOOL, the │ │ │ │value 0 implies FALSE and any nonzero │ │ │ │value implies TRUE. │ ├──────────┼──────────┼────────────────────────────────────────┤ │ch │CHAR │Signed eight-bit quantity; a character. │ ├──────────┼──────────┼────────────────────────────────────────┤ │s │SHORT │Signed 16-bit quantity; a SHORT. This is│ │ │ │often used in place of us when it does │ │ │ │not matter whether the value is signed │ │ │ │or unsigned. │ ├──────────┼──────────┼────────────────────────────────────────┤ │l │LONG │Signed 32-bit quantity; a LONG. This is │ │ │ │often used in place of ul when it does │ │ │ │not matter whether the value is signed │ │ │ │or unsigned. │ ├──────────┼──────────┼────────────────────────────────────────┤ │uch │UCHAR │Unsigned eight-bit quantity; a byte. │ │ │ │Same as b. │ ├──────────┼──────────┼────────────────────────────────────────┤ │us │USHORT │Unsigned 16-bit quantity. │ ├──────────┼──────────┼────────────────────────────────────────┤ │ul │ULONG │Unsigned 32-bit quantity. │ ├──────────┼──────────┼────────────────────────────────────────┤ │b │BYTE │Unsigned eight-bit quantity; a byte. │ │ │ │Same as uch. │ ├──────────┼──────────┼────────────────────────────────────────┤ │sz │CHAR[ ] │NULL-terminated string of characters. │ ├──────────┼──────────┼────────────────────────────────────────┤ │fb │UCHAR │Byte of flags, that is, an array of │ │ │ │flags packed in a BYTE. │ ├──────────┼──────────┼────────────────────────────────────────┤ │fs │USHORT │SHORT of flags, that is, an array of │ │ │ │flags packed in a USHORT. │ ├──────────┼──────────┼────────────────────────────────────────┤ │fl │ULONG │LONG of flags, that is, an array of │ │ │ │flags packed in a ULONG. The three │ │ │ │preceding types are used when more than │ │ │ │one flag is combined into a byte, SHORT │ │ │ │or LONG. Typically, the values are │ │ │ │combined with the OR operator and are │ │ │ │always unsigned. │ ├──────────┼──────────┼────────────────────────────────────────┤ │r │REAL │Real number, single precision 32-bits. │ ├──────────┼──────────┼────────────────────────────────────────┤ │rd │DOUBLE │Real number, double precision 64-bits. │ ├──────────┼──────────┼────────────────────────────────────────┤ │pfn │ │Pointer to a function. │ ├──────────┼──────────┼────────────────────────────────────────┤ │x │ │X-coordinate. │ ├──────────┼──────────┼────────────────────────────────────────┤ │y │ │Y-coordinate. │ └──────────┴──────────┴────────────────────────────────────────┘
The following standard prefixes are also defined:
┌──────────┬──────────────────────────────────────────────────┐ │Prefix │Description │ ├──────────┼──────────────────────────────────────────────────┤ │p │32-bit pointer for an 80386 microprocessor. For │ │ │example, pch is a pointer to a character. │ ├──────────┼──────────────────────────────────────────────────┤ │a │Array. For example, ach is an array of characters.│ ├──────────┼──────────────────────────────────────────────────┤ │i │Index to an array. For example, an ich is used to │ │ │index an ach. │ ├──────────┼──────────────────────────────────────────────────┤ │c │Count. For example, cch is a count of characters. │ ├──────────┼──────────────────────────────────────────────────┤ │d │Delta or difference between instances of a type. │ │ │For example, dx is the difference between two │ │ │values of x. │ ├──────────┼──────────────────────────────────────────────────┤ │h │Handle. A value that uniquely identifies an object│ │ │but cannot directly be used to access it. For │ │ │example, hps is a PS handle. │ ├──────────┼──────────────────────────────────────────────────┤ │mp │Mapping array. This prefix is always followed by │ │ │two base types rather than one and represents the │ │ │most general case of an array. Mathematically, an │ │ │array is a function mapping the index to the value│ │ │stored in the array. The prefix mp is an │ │ │abbreviation of map. In the construct mpab, a is │ │ │the type of the index and b is the type of the │ │ │value stored in the array. In most cases, the only│ │ │type that is important is the type of the value. │ │ │The index is usually an integer with no other │ │ │meaning (the a prefix is used in this instance). │ ├──────────┼──────────────────────────────────────────────────┤ │off │Offset. Generally used as an offset within a data │ │ │structure. The actual address of the element │ │ │within the data structure is derived by adding an │ │ │offset to a pointer, which points to the beginning│ │ │of the data structure. Normally, OFF is a byte │ │ │offset. For example: pfoo = (FOO *)((BYTE │ │ │*)pfooBase + 0fff00) │ ├──────────┼──────────────────────────────────────────────────┤ │id │Identifier. This is generally used for values that│ │ │identify some object. Usually the association of │ │ │the ID value and the object are established by the│ │ │programmer. For example, all windows are │ │ │identified by their Window ID, which can be set │ │ │and queried by the programmer. │ ├──────────┼──────────────────────────────────────────────────┤ │cmd │Command. Used for command values, typically as │ │ │function parameters. │ └──────────┴──────────────────────────────────────────────────┘
Some parameters are used in pairs; the qualifiers that are used reflect the relationship between the two variables. For example:
┌────────────┬───────────────────────────────────────────────────────────────────┐ │Parameter │Description │ ├────────────┼───────────────────────────────────────────────────────────────────┤ │First/Last │First and last elements in a set. These are typically used with │ │ │indexes or pointers (pchFirst, pchLast). Both values represent │ │ │valid values (compare with Min/Max below). For all valid values of │ │ │x: xFirst <= x <= xLast. The use of > with First or < with Last is │ │ │almost always an "off-by-one" error. │ │ │For example, to determine whether an ich is within ichFirst and │ │ │ichLast: if (ich >= ichFirst && ich <= ichLast) │ │ │ ... │ │ │A typical loop: │ │ │ for (ich = ichFirst; ich <= ichLast; ich++) │ │ │ ... │ ├────────────┼───────────────────────────────────────────────────────────────────┤ │Min/Max │Similar to First/Last except that Max is not a valid value in the │ │ │set (Min is a valid value). For all valid values of x in the set: │ │ │xMin < = x < xMax. The use of > with Min or < = with Max is almost │ │ │always an "off-by-one" error. │ │ │For example, to determine whether an ich is within ichMin and │ │ │ichMax: if (ich >= ichMin && ich < ichMax) │ │ │ ... │ │ │A typical loop: │ │ │ for (ich = ichMin; ich < /* or != */ ichMax; ich++) │ │ │ ... │ ├────────────┼───────────────────────────────────────────────────────────────────┤ │ │The current value (Cur) qualifier can be used with Min and Max when│ │ │Min or Max can change over time (for example, pbStackMaxCur). │ ├────────────┼───────────────────────────────────────────────────────────────────┤ │Old/New │Old and new. Typically used for values or states when it is │ │ │necessary to compare the old and new states of the value. │ ├────────────┼───────────────────────────────────────────────────────────────────┤ │Next/Prev │Next and previous. Typically used in situations in which items are │ │ │being enumerated, such as with linked lists. │ ├────────────┼───────────────────────────────────────────────────────────────────┤ │Src/Dst │Source and destination. Typically used in transfer operations. │ ├────────────┼───────────────────────────────────────────────────────────────────┤ │T │A temporary value. │ ├────────────┼───────────────────────────────────────────────────────────────────┤ │Save │A temporary saved value. Typically used when saving and restoring │ │ │some state. │ ├────────────┼───────────────────────────────────────────────────────────────────┤ │Cur │Current value. │ └────────────┴───────────────────────────────────────────────────────────────────┘
The base types and their prefixes are defined as follows:
┌──────────┬──────────────────────────────────────────────────┐ │Data Type │Prefix │ ├──────────┼──────────────────────────────────────────────────┤ │PSZ │psz │ ├──────────┼──────────────────────────────────────────────────┤ │PCH │pch │ ├──────────┼──────────────────────────────────────────────────┤ │HAB │hab │ ├──────────┼──────────────────────────────────────────────────┤ │HPS │hps │ ├──────────┼──────────────────────────────────────────────────┤ │HDC │hdc │ ├──────────┼──────────────────────────────────────────────────┤ │HRGN │hrgn │ ├──────────┼──────────────────────────────────────────────────┤ │HBITMAP │hbmp │ ├──────────┼──────────────────────────────────────────────────┤ │PLONG │pl │ ├──────────┼──────────────────────────────────────────────────┤ │POINTL │ptl │ ├──────────┼──────────────────────────────────────────────────┤ │POINTL │pt │ ├──────────┼──────────────────────────────────────────────────┤ │RECTL │rcl │ ├──────────┼──────────────────────────────────────────────────┤ │RECTL │rc │ ├──────────┼──────────────────────────────────────────────────┤ │HWND │hwnd │ ├──────────┼──────────────────────────────────────────────────┤ │WPOINT │wpt │ ├──────────┼──────────────────────────────────────────────────┤ │WRECT │wrc │ ├──────────┼──────────────────────────────────────────────────┤ │FIXED │fx │ └──────────┴──────────────────────────────────────────────────┘
Parameters for defined structures are the defined parameter names. For example:
──────────────────────────────────────────────────────────────
AREADEFS struct
{
defSet
fFlags
CodePage
}AREADEFS
──────────────────────────────────────────────────────────────
System-defined constants and flags are represented as two or more uppercase WORDs or mnemonic abbreviations separated by underscores. For example, SYS_CONSTANT and SYS_FLAG.