papers on Hungarian notation comp.software-eng archive file "hungarian" last changed 11 Oct 1991 This file contains information on the following subjects. Numbers in column 1 count distinct messages with the corresponding subject. 2 Hungarian Notation References ------------------------------------------------------------------------ Date: Fri, 20 Sep 91 15:12:53 -0700 From: sgihbtn!billc@uunet.UU.NET (Bill Campbell) Message-Id: <9109202212.AA04579@shared> To: uunet!umiacs.UMD.EDU!dalamb@uunet.UU.NET Subject: Re: Hungarian Notation References I have just talked with Doug Klunder at Microsoft. He says that publication of his paper is perfectly okay, they have not copyrighted it. It is, of course, their preference that the document be respresented as his/MS's work. Date: Wed, 11 Sep 91 09:26:24 -0700 From: sgihbtn!billc@uunet.UU.NET (Bill Campbell) Subject: Re: Hungarian Notation References See the attached shell archive. The shar table of contents is annotated. For the *roff files, the correct invocation of *roff is documented in a comment at the top of the file. Now that I've provided you with this, let me also add that I don't recommend it's use, unless you are working with MS Windows or Presentation Manager, where the environment (library routines, predeclared identifiers) already use it. We tried to use it in the X11/Motif environment for about a year and decided that it was a LOT more trouble than it was worth, even after we got over the "learning curve". Regards, **************************************************************************** * Bill Campbell * "Now the new reality is that program- * * Software Engineer * mers ... can learn to consistently * * Sierra Geophysics, Inc. * write programs which are error-free * * sgihbtn!billc@uunet.uu.net * from their inception.... Just * * * knowing that it is possible is half * * * the battle. Learning how to write * * * such programs is the other half." * * * -Harlan Mills * **************************************************************************** #include # This is a shell archive. Remove everything before this line. # Unpack it by saving it in a file and typing "sh file". # # Wrapped by billc at shared on Tue Sep 10 14:21:29 PDT 1991. # # this archive contains: # hung.nr (41829 bytes) - original paper by Doug Klunder, *roff source # hung.ascii (46483 bytes) - DK's paper in ascii format # hungqr.mm (10803 bytes) - A quick reference distillation, *roff -mm fmt # hungqr.ascii (15673 bytes) - Quick reference in ascii format # iemis.m4 (399 bytes) - m4 macros, necessary to translate hung.nr # iemis.tmac (1566 bytes) - *roff macros, necessary to translate hung.nr # echo Extracting hung.nr... 1>&2 if test -f hung.nr ; then echo "will not overwrite hung.nr" 1>&2 else sed 's/^X//' > hung.nr <<\!!!EOF!!! X.\" m4 iemis.tmac iemis.m4 %s | nroff -ms X.\" $Header: /disk2/d3c962/iemis/RCS/hung.nr,v 1.2 90/05/23 12:03:59 d3c962 Exp Locker: d3c962 $ X.ds CF -%- X.ds CH X.TL XHUNGARIAN NAMING CONVENTIONS X.AU XDoug Klunder X.ND XJanuary 18, 1988 X X.1H INTRODUCTION X X.LP XThis document describes a set of naming conventions used by the PROJECT_NAME Xproject in development of the software. The initial naming conventions Xwhere taken from a NAMING CONVENTIONS document authored by Doug Klunder Xat MicroSoft. These conventions commonly go by the name "Hungarian," Xreferring both to the nationality of their original developer, Charles XSimonyi, and also to the fact that to an uninitiated programmer they Xare somewhat confusing. Once you have gained familiarity with XHungarian, however, we believe that you will find that the clarity of Xcode is enhanced. For convenience, this memo first describes how to Xuse Hungarian, and then describes why it is useful; the general Xapproach is from a programming viewpoint, rather than a mathematical Xone. X X.1H THE RULES X X.LP XHungarian is largely language independent; it is equally applicable to Xa microprocessor assembly language and to a fourth-generation database Xapplication language (and has been used in both). However, there is a Xlittle flavor of C, in that arrays and pointers to arrays are not Xclearly distinguished. While this may sound confusing, in practice Xthere is little ambiguity. X X.DS X< prefix > < base type > < qualifier > X.DE X X.2H VARIABLES X X.LP XThe most common type of identifier is a variable name. All variable Xnames are composed of three elements: prefixes, base type, and Xqualifier. (These are also referred to as constructors, tag, and Xqualifier). Not all elements are present in all variable names; the Xonly part that is always present is the base type. This type should Xnot be confused with the types supported directly by the programming Xlanguage; most types are application specific. For example, an 1b1 Xtype could refer to a structure containing symbol information; a co Xcould be a value specifying a color. X X.3H Base Types (Tags) X X.LP XType that are not `define'd must be added As the above examples indicate, Xtags should be short (typically two or three letters) and somewhat Xmnemonic. Because of the brevity, the mnemonic value will be useful Xonly as a reminder to someone who knows the application, and has been Xtold what the basic types are; the name will not be sufficient to Xinform (by itself) a casual viewer what is being referred to. For Xexample, a co could just as easily refer to a geometric coordinate, or Xto a commanding officer. Within the context of a given application, Xhowever, a co would always have a specific meaning; all co's would Xrefer to the same type of object, and all references to such an object Xwould use the term co. X X.LP XOne should resist the natural first impulse to use a short descriptive Xgeneric English term as a type name. This is almost always a mistake. XOne should not preempt the most useful English phrases for the Xprovincial purposes of any given version of a given program. Chances Xare that the same generic term could be equally applicable to many more Xtypes in the same program. How will we know which is the one with the Xpretty "logical" name, and which have the more arbitrary variants Xtypically obtained by omitting various vowels or by other Xdisfigurement? Also, in communicating with other programmers, how do Xwe distinguish the generic use of the common term from the reserved Xtechnical usage? In practice, it seems best to use some abbreviated or Xform of the generic term, or perhaps an acronym. In speech, the tag Xmay be spelled out, or a pronounceable nickname may be used. In time, Xthe exact derivation of the tag may be forgotten, but its meaning will Xstill be clear. X X.LP XAs is probably obvious from the above, it is essential that all tags Xused in a given application be clearly documented. This is extremely Xuseful in helping a new programmer learn the code; it not only enables Xhim (or her) to decode the otherwise cryptic names, but it also serves Xto describe the underlying concepts of the program, since the data Xtypes tend to determine how the program works. It is also worth Xpointing out that this is not nearly as onerous as it sounds; while Xthere may be tens of thousands of variables in a program, the number of Xtypes is likely to be quite small. X X.LP XAlthough most types are particular to a given application, there are a Xfew standard ones that appear in many different ones; synonyms for Xthese types should never be used: X X.IP f Xa flag (boolean, logical). The qualifier (see below) should describe Xthe condition that will cause this flag to be set (e.g., fError would Xbe clear if there were no error, set if one exists). This tag may Xrefer to a single bit, a byte, or a word; often it will be an object of Xtype BOOL (`define'd by the application, usually as int). Usually the Xobject referred to will contain either 1 (fTrue, TRUE) or 0 (fFalse, XFALSE). In some instances, other values may be used, either for Xefficiency or historical reasons; such a use usually indicates that Xanother type may be more appropriate. X X.IP ch Xa one-byte character. Note that this is not adequate for Kanji. X X.IP st Xa Pascal-type string (first byte is count, remainder is the actual Xcharacters). Typically refers to a pointer to the actual memory. This Xshould be the most common type of string used in the Applications Xgroup; it is more efficient than an sz (below). X X.IP sz Xa zero-terminated string, or a pointer to it. These are most often Xused to interface to an operating system (or equivalent) that requires Xthem; for most other uses, an st is preferable. Unfortunately, C Xstring constants are normally zero- terminated, so it takes a little Xmore effort to use st's; the effort is worth it. The Applications XDevelopment compiler proves ways to make strings constants st's. X X.IP fn Xa function. Since about the only thing you can do with a function is Xtake its address, this almost always has a "p" prefix (see below). For Xthis reason, in some applications fn is itself used to mean pointer to Xa function. X X.IP fl Xa file structure supplied by operating systems. X X.LP XThere are some more types that appear in many applications; they should Xonly be used for the most generic purposes: X X.IP w Xa word (typically 16 bits). For most purposes, this is an incorrect Xusage, since the usage of the word is specific to a particular type of Xwork, and should be so distinguished. Correct usages are generally Xlimited to generic subroutines (e.g., sort an array of words) that can Xdeal with a number of different types; another common use is in Xconjunction with the prefix c (see below), to produce a count of words X(the size) for some object. The exact meaning of w is also somewhat Xloose; it sometimes means a signed quantity and sometimes unsigned. X X.IP b Xa byte (typically 8 bits). The same warnings apply to this as to w. X X.IP l Xa long (typically 32 bits). The same warnings apply to this as to w. X X.IP uw XUnsigned word. X X.IP ul XUnsigned long. X X.IP d XDouble (double precision) X X.IP r XFloat (single precision) X X.IP bit Xa single bit. Typically used to specify bits used within other types. XThis concept is usually better handled with the "f" and "sh" prefixes X(see below). X X.IP v Xa void. This corresponds to the C definition of void, meaning that the Xtype is not specified. This type will never be used without a "p" Xprefix since it is not possible to have an unspecified type for a Xvariable; conceivably there are additional prefixes (e.g., ppv), but Xsuch a usage is unlikely. It is perfectly valid to assign a pv to a Xpointer of any other type, or vice versa. The major use of this type Xis for generic subroutines (such as allocate and free) which return or Xtake as arguments pointers of various types. X X.LP XThere a few types that are used widely within the applications group, Xbut may not be applicable to others: X X.IP env Xan environment. Used to implement non-local goto's (SetJmp Xand DoJmp). The exact format of an env (including size), Xvaries from system to system. X X.IP sb Xa segment base. The part of a segmented pointer that determines Xthe segment. The exact implementation varies from Xsystem to system. These are used directly in some applications Xfor efficiency; the same results can be obtained (less Xefficiently) through the use of far or huge pointers. X X.IP ib Xan offset. The part of a pointer that determines the offset Xwithin a segment. These are used directly in some applications Xfor efficiency; the same results can be obtained (less Xefficiently) through the use of far or huge pointers. For the Xliteral-minded, ib is not really a new type at all; it is simply Xthe prefix i (`index') applied to the type b (byte), with the Xviewpoint that a segment is just an array of bytes. Many people Xprefer to consider it a true indivisible base type. X X.3H Prefixes (Constructors) X X.LP XBase types are not by themselves sufficient to fully describe the type Xof a variable, since variables often refer to more complex items. The Xmore complex items are always derived from some combination of simple Xitems, with a few operations. For example, there may be a pointer to Xan lbl, or an array of them, or a count of co's. These operations are Xrepresented in Hungarian by prefixes; the combination of the prefixes Xand base type represent the complete type of an entity. Note that a Xtype may consist of multiple prefixes in addition to the base type X(e.g., a pointer to a count of co's); the prefixes are read right to Xleft, with each prefix applying to the remainder of the type (see Xexamples below). The term constructor is used because a new type is Xconstructed from the combination of the operation and the base type. X X.LP XIn theory, new prefixes can be created, just as new types are routinely Xcreated for each application. In practice, very few new prefixes have Xbeen created over the years, as the set that already exists is rather Xcomprehensive for operations likely to be applied to types. Prefixes Xthat have been added tend to deal with the specifics of machine Xarchitecture, and are variations on existing prefixes (i.e., different Xflavors of pointers). Once can go overboard in refusing to create a Xnew prefix, however; some new concepts really are logically expressed Xas prefixes, not types. A couple of examples of incorrect usage in the Xlist below derived from the reluctance to create a new prefix. X X.LP XThe standard prefixes are: X X.IP p Xa pointer. A 32 bit address. (assumed to be a far pointer). X X.IP rg Xan array, or a pointer to it. The name comes from a Xmathematical viewpoint of an array as the range of a function X(see mp and dn below). For example, an rgch is an array of Xcharacters; a pch could point to one of the characters in the Xarray. Note that it is perfectly reasonable to assign an rgch Xto a pch; pch points to the first character in the array. X X.IP i Xan `index' into an array. For example, an ich is used to `index' Xan rgch. X X.IP c Xa count. For example, the first byte of an st is a count of Xcharacters, or a cch. X X.IP d Xa difference between two instances of a type. This is often Xconfused with a count, but is in reality quite separate. For Xexample, a cch could refer t the number of characters in a Xstring, whereas a dch could refer to the difference between Xthe values 'a' and 'A'. The confusion arises when dealing Xwith indices; a dich (difference between indices into a Xcharacter array) is equivalent to a cch (count of characters); Xwhich one to use depends on the viewpoint. This gets most Xconfusing when dealing with base types that are in effect Xindices, though not specifically labelled as such. For Xexample, a spreadsheet could have a rw type that indicates a Xrow in the spreadsheet; it does not contain the actual data Xfor the row, but is simply a one-word integer specifying the Xrow number. A type specifying a count of rows (not rw's) would Xcorrectly be a drw (difference between row numbers), not a crw X(count of row numbers). X X.IP h Xa handle. This is often a pointer to a pointer (used to allow Xmoveable heap objects). The types of the pointers may vary Xamoung applications; the two most common cases are a near Xpointer to a near pointer (h is equivalent to pp) and a far Xpointer to a far pointer (h is equivalent to lplp). Most Xcommonly used for interface to an operating system; within Xapplications, moveable objects can be handled through huge Xpointers. In some systems (e.g., Windows) a handle is not a Xpointer to a pointer. To avoid confusion it may be best to Xuse pp (or lplp) as prefixes when the application is actually Xgoing to do the indirection, and reserve h for instances in Xwhich the handle is just passed on to the system. Doing this Xprevents the most common misuse of h in defining a handle to Xan array (or other implicit pointer type); uses of hsz to imply Xtwo indirections to obtain a character are incorrect. This Xshould properly be done as a psz or, if h must be used, as an Xhasz (see 'a' prefix below). X X.IP gr Xa group, or a pointer to it. This is similar to an rg, but is Xused for variable size objects. In this case an `index' (i) is Xnot particularly useful, since it can not be used directly to Xobtain an object (one can, of course, write a routine that Xwill take the gr and i, walk through the data in a type- Xspecific manner, and derive a pointer to the object desired). XThis is a rarely used prefix, and in some code, grp has been Xused instead of gr. X X.IP b Xan offset. This is typically used in conjunction with a gr, Xin place of an i, in order to get around the problem mentioned Xabove. This offset is in terms of bytes, so Xpfoo-(BYTE *)grfoo+bfoo. As with gr, this is a somewhat rare Xusage in current code. b originally stood for base-relative Xpointer, but should really be considered to be an offset within Xa data structure; true base-relative pointers are just near Xpointers (p); the base is the segment they are within. X X.IP mp Xan array. This prefix is followed by two types, rather than Xthe standard one, and represents the most general case of an Xarray. From a mathematical viewpoint, an array is simply a Xfunction mapping the `index' to the value stored in the array X(hence mp as an abbreviation of map). In the construct mpxy, Xx is the type of the `index' and y is the type of the value Xstored in the array (hence mp as an abbreviation of map). In Xthe construct myxy, x is the type of the `index' and y is the Xtype of the value stored in the array. In most cases, the Xonly type that is important is the type of the value; the `index' Xis always an integer with no other meaning. In this case, an Xrg is used; this means that the rgs is equivalent to an mpixx. X(This also explains the weird prefix rg; it is an abbreviation Xfor range). X X.IP dn Xan array. This is used in the rare case that the important Xpart of the array mapping is the `index', not the value. dn is Xan abbreviation for domain. Only a few of these are used in Xthe entire Applications group; an example of a plausible use Xis given in the discussion of e, below. X X.IP e Xan element of an array. This is used in conjunction with a dn X(and is thus just as rare); it is the type of the value stored Xin a dn. Just as rgx is equivalent to mpixx, dnx is equivalent Xto mpxex. An example of use is the native code generation Xpart of the CS compiler; there is a type vr (an acronym for Xvirtual register). A vr is just a simple integer, specifying Xwhich register to use for various pieces of code output. XHowever, there is quite a bit more information than just a Xnumber that is associated with each register. This additional Xdata is stored in a structure called an evr; there is an array Xof them called dnvr. Thus, the information for a given register Xcan be found with the expression dnvr[vr]. X X.IP f Xa bit within a type. This is a new prefix that is currently used Xonly by a few projects, but is now the approved method Xfor dealing with bits. It is typically used for overloading Xan integer type with one or more bit flags, in otherwise unused Xportions of the integer. This should not be confused with the Xf type, in which the entire value is used to contain the flag. XAn example is a scan mode (type sm), with possible values XsmForward and smBackwards. Since the basic mode only requires Xa few bits (in this case only one bit), the remainder of a Xword can be used to encode other information. One bit is used Xfor fsmWrap, another for fsmCaseInsens. Here the f is a prefix Xto the sm type, specifying only a single bit is used. X X.IP sh Xa `shift' amount. This is another new prefix used to deal with Xbits within other types (complementing the "f" prefix); it Xspecifies the location within the type by a bit number (rather Xthan the bit mask which the "f" prefix specifies). It actually Xis followed by two types; the first type is the type being X`shift'ed (almost always an f), and the second type is the type Xthe bits are stored within. Continuing the above example of Xscan modes, if fsmWrap has a value of 4000 hex, shfsmWrap would Xhave the value of 14. X X.IP u Xa union. This is a rarely used prefix; it is used for Xvariables that can hold one of several types. In practice Xthis becomes unwieldy. An example is a urwcol, which can hold Xeither a rw type or a col type. X X.IP a Xan allocation. This is a rarely used prefix; it is used to Xdistinguish between an array and a pointer to it. Thus, sz is Xa pointer to a null-terminated string and asz is the actual Xallocated space. a is almost invariably used in conjunction Xwith a pointer-type prefix, in order to allow the pointer to Xbe explicit (rather than implicit, as with an sz). It is Xessentially the inverse of a p prefix, so pasz is equivalent Xto sz. Its best use is with the h prefix; hasz is a handle to Xa null-terminated string. Most of the current Applications Xcode (incorrectly) omits the a. X X.IP v XA global variable X X X.4H Some Examples X X.LP XSince the prefixes and base types both appear in lower case, with no Xseparating punctuation, ambiguity can arise. Is pfc a tag of its own X(e.g., for a private first class), or is it a pointer to an fc? Such Xquestions can be answered only if one is familiar with the specific Xtypes used in a program. To avoid problems like this it is often wise Xto avoid creating base type names that begin with any of the common Xprefixes. In practice, ambiguity does not seem to be a problem. The Xidea of additional punctuation to remove the ambiguity has been shown Xto be impractical. X X.LP XThe following list contains both common and rarer usages: X X.nr PI 12m X X.IP pch Xa pointer to a character. X X.IP ich Xan `index' into an array of character. X X.IP rgst Xan array of Pascal-type strings. Hungarian is not sufficient Xin itself to indicate whether this is an array of characters Xor an array of pointers; since strings are usually variable Xlength, it is probably a safe bet that this is an array of Xpointers to the actual characters. X X.IP grst Xa group of Pascal-type strings. As with the above example, Xthis could be either an array of characters or of pointers; Xsince it is a gr, not an rg, it is probably safe to assume Xthat it is an array of characters. X X.IP bst Xan offset to a particular Pascal-type string in a grst. X.IP phpx Xa near pointer to a huge pointer to an object of type x. X X.IP pich Xa near pointer to an `index' into a character array. A common Xuse for something like this is passing a pointer as a parameter Xto a function so that a return value can be stored through the Xpointer; pich would be extremely unlikely to be used in an Xexpression without indirection (pich+=2 is probably gibberish; X(*pich)+=2 may well be meaningful). X X.IP en Xprobably a base type (such as an entry). Conceivably it is an Xelement for an array `index'ed by an n; only knowledge of the Xapplication can tell for certain. X X.IP hrgn Xhandle to a region. Again there is ambiguity; this could be Xinterpreted as a handle to an array of n's or a huge pointer Xto an array of n's. X X.IP dx Xlength of a horizontal line (difference between x coordinates). X X.IP rgrgx Xa two-dimensional array of x's (an array of arrays of x's). X X.IP mpminpfn Xan array of pointers to functions, `index'ed by mi's. For Xexample, an mi could be a menu item, and this array could be Xused for a command dispatch. Again, context makes the parsing Xclear; this could equally well be interpreted as an array of Xfn's (perhaps friendly nukes), `index'ed by mip's (perhaps Xmissile placements). X X.IP pv Xpointer to a void. Could be used as an argument to Free. X X.IP hrgch Xhuge pointer to an array of characters. Could instead be Xinterpreted as a handle to an array of characters, depending Xon the application. X X.nr PI 5m X X.3H Qualifiers X X.LP XWhile the prefixes and base type are sufficient to fully specify the Xtype of a variable, this may not be sufficient to distinguish the Xvariable. If there are two variables of the same type within the same Xcontext, further specification is required to disambiguate. This is Xdone with qualifiers. A qualifier is a short descriptive word (or Xfacsimile; good English is not required) that indicates what the Xvariable is used for. In some cases, multiple words may be used. Some Xdistinctive punctuation should be used to separate the qualifier from Xthe type; in C and other languages that support it, this is done by Xmaking the first letter of the qualifier upper-case. (If multiple Xwords are used, the first letter of each should be upper-case; the Xremainder of the name, both type and qualifier, is always lower-case. XThere is one special case to watch out for; `define'd constants Xspecifying the size of a type are often of the form cbFOO or cwFOO, Xwhere foo is the type. Strictly speaking only the F in FOO should be Xcapitalized, but the incorrect usage is fairly common.) X X.LP XExactly what constitutes a naming context is language specific; within XC the contexts are individual blocks (compound statements), procedures, Xdata structures (for naming fields), or the entire program (globals). XAs a matter of good programming style, it is not recommended that Xhiding of names be used; this means that any context should be Xconsidered to `include' all of its subcontexts. (In other words, don't Xgive a local the same name as a global.) If there is no conflict within Xa given context (only one variable of a given type), it is not Xnecessary to use a qualifier; the type alone serves to identify the Xvariable. In small contexts (data structures or small procedures), a Xqualifier should not be used except in case of conflict; in larger Xcontexts it is often a good idea to use a qualifier even when not Xnecessary, since later modification of the code may make it necessary. XIn cases of ambiguity, one of the variables may be left with no Xqualifier; this should only be done if it is clearly more important Xthan the other variables of the same type (no qualifier implies primary Xusage). X X.LP XSince many uses of variables fall into the same basic categories, there Xare several standard qualifiers. If applicable, one of these should be Xused, since they specify meaning with no chance of confusion. In the Xcase of multiple word qualifiers, the order of the words is not Xcrucial, and should be chosen for clarity; if one of the words is a Xstandard qualifier, it should probably come last (unfortunately, this Xsuggestion is by no means uniformly followed). The standard qualifiers Xare: X X.nr PI 12m X X.IP First Xthe first element in a set. This is usually used with an `index' Xor a pointer (e.g., pchFirst), referring to the first element Xof an array to be dealt with. The `index' may be an implied X`index' (as with a rw type in a spreadsheet). X X.IP Last Xthe last element in a set. This is usually used with an `index' Xor a pointer (e.g., pchLast), referring to the last element of Xan array to be dealt with). Both First and Last represent Xvalid values (compare with Lim below); they are often paired, Xas in this common loop: for (ich=ichFirst; ich<=ichLast; Xich++) X X.IP Lim Xthe upper limit of elements in a set. This is not a valid Xvalue; for all valid values f x, x&2 if test -f hung.ascii ; then echo "will not overwrite hung.ascii" 1>&2 else sed 's/^X//' > hung.ascii <<\!!!EOF!!! X X X X X X X X X X HUNGARIAN NAMING CONVENTIONS X X X Doug Klunder X January 18, 1988 X X X X X X X X XSeptember 10, 1991 X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X1. INTRODUCTION X X XThis document describes a set of naming conventions used by Xthe IEMIS project in development of the software. The ini- Xtial naming conventions where taken from a NAMING CONVEN- XTIONS document authored by Doug Klunder at MicroSoft. XThese conventions commonly go by the name "Hungarian," Xreferring both to the nationality of their original Xdeveloper, Charles Simonyi, and also to the fact that to an Xuninitiated programmer they are somewhat confusing. Once Xyou have gained familiarity with Hungarian, however, we Xbelieve that you will find that the clarity of code is Xenhanced. For convenience, this memo first describes how to Xuse Hungarian, and then describes why it is useful; the gen- Xeral approach is from a programming viewpoint, rather than a Xmathematical one. X X X2. X2.THE RULES X X XHungarian is largely language independent; it is equally Xapplicable to a microprocessor assembly language and to a Xfourth-generation database application language (and has Xbeen used in both). However, there is a little flavor of C, Xin that arrays and pointers to arrays are not clearly dis- Xtinguished. While this may sound confusing, in practice Xthere is little ambiguity. X X X < prefix > < base type > < qualifier > X X X X2.1. X2.1.VARIABLES X X XThe most common type of identifier is a variable name. All Xvariable names are composed of three elements: prefixes, Xbase type, and qualifier. (These are also referred to as Xconstructors, tag, and qualifier). Not all elements are Xpresent in all variable names; the only part that is always Xpresent is the base type. This type should not be confused Xwith the types supported directly by the programming Xlanguage; most types are application specific. For example, Xan 1b1 type could refer to a structure containing symbol Xinformation; a co could be a value specifying a color. X X X X X X X X X X X X X X2.1.1. X2.1.1.Base Types (Tags) X X XType that are not defined must be added As the above exam- Xples indicate, tags should be short (typically two or three Xletters) and somewhat mnemonic. Because of the brevity, the Xmnemonic value will be useful only as a reminder to someone Xwho knows the application, and has been told what the basic Xtypes are; the name will not be sufficient to inform (by Xitself) a casual viewer what is being referred to. For Xexample, a co could just as easily refer to a geometric Xcoordinate, or to a commanding officer. Within the context Xof a given application, however, a co would always have a Xspecific meaning; all co's would refer to the same type of Xobject, and all references to such an object would use the Xterm co. X X XOne should resist the natural first impulse to use a short Xdescriptive generic English term as a type name. This is Xalmost always a mistake. One should not preempt the most Xuseful English phrases for the provincial purposes of any Xgiven version of a given program. Chances are that the same Xgeneric term could be equally applicable to many more types Xin the same program. How will we know which is the one with Xthe pretty "logical" name, and which have the more arbitrary Xvariants typically obtained by omitting various vowels or by Xother disfigurement? Also, in communicating with other pro- Xgrammers, how do we distinguish the generic use of the com- Xmon term from the reserved technical usage? In practice, it Xseems best to use some abbreviated or form of the generic Xterm, or perhaps an acronym. In speech, the tag may be Xspelled out, or a pronounceable nickname may be used. In Xtime, the exact derivation of the tag may be forgotten, but Xits meaning will still be clear. X X XAs is probably obvious from the above, it is essential that Xall tags used in a given application be clearly documented. XThis is extremely useful in helping a new programmer learn Xthe code; it not only enables him (or her) to decode the Xotherwise cryptic names, but it also serves to describe the Xunderlying concepts of the program, since the data types Xtend to determine how the program works. It is also worth Xpointing out that this is not nearly as onerous as it Xsounds; while there may be tens of thousands of variables in Xa program, the number of types is likely to be quite small. X X XAlthough most types are particular to a given application, Xthere are a few standard ones that appear in many different Xones; synonyms for these types should never be used: X X X X X X X X X X X X X Xf a flag (boolean, logical). The qualifier (see below) X should describe the condition that will cause this flag X to be set (e.g., fError would be clear if there were no X error, set if one exists). This tag may refer to a X single bit, a byte, or a word; often it will be an X object of type BOOL (defined by the application, usu- X ally as int). Usually the object referred to will con- X tain either 1 (fTrue, TRUE) or 0 (fFalse, FALSE). In X some instances, other values may be used, either for X efficiency or historical reasons; such a use usually X indicates that another type may be more appropriate. X X Xch a one-byte character. Note that this is not adequate X for Kanji. X X Xst a Pascal-type string (first byte is count, remainder is X the actual characters). Typically refers to a pointer X to the actual memory. This should be the most common X type of string used in the Applications group; it is X more efficient than an sz (below). X X Xsz a zero-terminated string, or a pointer to it. These X are most often used to interface to an operating system X (or equivalent) that requires them; for most other X uses, an st is preferable. Unfortunately, C string X constants are normally zero- terminated, so it takes a X little more effort to use st's; the effort is worth it. X The Applications Development compiler proves ways to X make strings constants st's. X X Xfn a function. Since about the only thing you can do with X a function is take its address, this almost always has X a "p" prefix (see below). For this reason, in some X applications fn is itself used to mean pointer to a X function. X X Xfl a file structure supplied by operating systems. X X XThere are some more types that appear in many applications; Xthey should only be used for the most generic purposes: X X Xw a word (typically 16 bits). For most purposes, this is X an incorrect usage, since the usage of the word is X specific to a particular type of work, and should be so X distinguished. Correct usages are generally limited to X generic subroutines (e.g., sort an array of words) that X can deal with a number of different types; another X X X X X X X X X X X X X common use is in conjunction with the prefix c (see X below), to produce a count of words (the size) for some X object. The exact meaning of w is also somewhat loose; X it sometimes means a signed quantity and sometimes X unsigned. X X Xb a byte (typically 8 bits). The same warnings apply to X this as to w. X X Xl a long (typically 32 bits). The same warnings apply to X this as to w. X X Xuw Unsigned word. X X Xul Unsigned long. X X Xd Double (double precision) X X Xr Float (single precision) X X Xbit a single bit. Typically used to specify bits used X within other types. This concept is usually better X handled with the "f" and "sh" prefixes (see below). X X Xv a void. This corresponds to the C definition of void, X meaning that the type is not specified. This type will X never be used without a "p" prefix since it is not pos- X sible to have an unspecified type for a variable; con- X ceivably there are additional prefixes (e.g., ppv), but X such a usage is unlikely. It is perfectly valid to X assign a pv to a pointer of any other type, or vice X versa. The major use of this type is for generic sub- X routines (such as allocate and free) which return or X take as arguments pointers of various types. X X XThere a few types that are used widely within the applica- Xtions group, but may not be applicable to others: X X Xenv an environment. Used to implement non-local goto's X (SetJmp and DoJmp). The exact format of an env X (including size), varies from system to system. X X Xsb a segment base. The part of a segmented pointer that X X X X X X X X X X X X X determines X X the segment. The exact implementation varies from sys- X tem to system. These are used directly in some appli- X cations for efficiency; the same results can be X obtained (less efficiently) through the use of far or X huge pointers. X X Xib an offset. The part of a pointer that determines the X offset within a segment. These are used directly in X some applications for efficiency; the same results can X be obtained (less efficiently) through the use of far X or huge pointers. For the literal-minded, ib is not X really a new type at all; it is simply the prefix i X (index) applied to the type b (byte), with the X viewpoint that a segment is just an array of bytes. X Many people prefer to consider it a true indivisible X base type. X X X2.1.2. X2.1.2.Prefixes (Constructors) X X XBase types are not by themselves sufficient to fully Xdescribe the type of a variable, since variables often refer Xto more complex items. The more complex items are always Xderived from some combination of simple items, with a few Xoperations. For example, there may be a pointer to an lbl, Xor an array of them, or a count of co's. These operations Xare represented in Hungarian by prefixes; the combination of Xthe prefixes and base type represent the complete type of an Xentity. Note that a type may consist of multiple prefixes Xin addition to the base type (e.g., a pointer to a count of Xco's); the prefixes are read right to left, with each prefix Xapplying to the remainder of the type (see examples below). XThe term constructor is used because a new type is con- Xstructed from the combination of the operation and the base Xtype. X X XIn theory, new prefixes can be created, just as new types Xare routinely created for each application. In practice, Xvery few new prefixes have been created over the years, as Xthe set that already exists is rather comprehensive for Xoperations likely to be applied to types. Prefixes that Xhave been added tend to deal with the specifics of machine Xarchitecture, and are variations on existing prefixes (i.e., Xdifferent flavors of pointers). Once can go overboard in Xrefusing to create a new prefix, however; some new concepts Xreally are logically expressed as prefixes, not types. A Xcouple of examples of incorrect usage in the list below Xderived from the reluctance to create a new prefix. X X X X X X X X X X X X XThe standard prefixes are: X X Xp a pointer. A 32 bit address. (assumed to be a far X pointer). X X Xrg an array, or a pointer to it. The name comes from a X mathematical viewpoint of an array as the range of a X function (see mp and dn below). For example, an rgch X is an array of characters; a pch could point to one of X the characters in the array. Note that it is perfectly X reasonable to assign an rgch to a pch; pch points to X the first character in the array. X X Xi an index into an array. For example, an ich is used to X index an rgch. X X Xc a count. For example, the first byte of an st is a X count of characters, or a cch. X X Xd a difference between two instances of a type. This is X often confused with a count, but is in reality quite X separate. For example, a cch could refer t the number X of characters in a string, whereas a dch could refer to X the difference between the values 'a' and 'A'. The X confusion arises when dealing with indices; a dich X (difference between indices into a character array) is X equivalent to a cch (count of characters); which one to X use depends on the viewpoint. This gets most confusing X when dealing with base types that are in effect X indices, though not specifically labelled as such. For X example, a spreadsheet could have a rw type that indi- X cates a row in the spreadsheet; it does not contain the X actual data for the row, but is simply a one-word X integer specifying the row number. A type specifying a X count of rows (not rw's) would correctly be a drw X (difference between row numbers), not a crw (count of X row numbers). X X Xh a handle. This is often a pointer to a pointer (used X to allow moveable heap objects). The types of the X pointers may vary amoung applications; the two most X common cases are a near pointer to a near pointer (h is X equivalent to pp) and a far pointer to a far pointer (h X is equivalent to lplp). Most commonly used for inter- X face to an operating system; within applications, move- X able objects can be handled through huge pointers. In X some systems (e.g., Windows) a handle is not a pointer X to a pointer. To avoid confusion it may be best to use X X X X X X X X X X X X X pp (or lplp) as prefixes when the application is actu- X ally going to do the indirection, and reserve h for X instances in which the handle is just passed on to the X system. Doing this prevents the most common misuse of X h in defining a handle to an array (or other implicit X pointer type); uses of hsz to imply two indirections to X obtain a character are incorrect. This should properly X be done as a psz or, if h must be used, as an hasz (see X 'a' prefix below). X X Xgr a group, or a pointer to it. This is similar to an rg, X but is used for variable size objects. In this case an X index (i) is not particularly useful, since it can not X be used directly to obtain an object (one can, of X course, write a routine that will take the gr and i, X walk through the data in a type- specific manner, and X derive a pointer to the object desired). This is a X rarely used prefix, and in some code, grp has been used X instead of gr. X X Xb an offset. This is typically used in conjunction with X a gr, in place of an i, in order to get around the X problem mentioned above. This offset is in terms of X bytes, so pfoo-(BYTE *)grfoo+bfoo. As with gr, this is X a somewhat rare usage in current code. b originally X stood for base-relative pointer, but should really be X considered to be an offset within a data structure; X true base-relative pointers are just near pointers (p); X the base is the segment they are within. X X Xmp an array. This prefix is followed by two types, rather X than the standard one, and represents the most general X case of an array. From a mathematical viewpoint, an X array is simply a function mapping the index to the X value stored in the array (hence mp as an abbreviation X of map). In the construct mpxy, x is the type of the X index and y is the type of the value stored in the X array (hence mp as an abbreviation of map). In the X construct myxy, x is the type of the index and y is the X type of the value stored in the array. In most cases, X the only type that is important is the type of the X value; the index is always an integer with no other X meaning. In this case, an rg is used; this means that X the rgs is equivalent to an mpixx. (This also explains X the weird prefix rg; it is an abbreviation for range). X X Xdn an array. This is used in the rare case that the X important part of the array mapping is the index, not X the value. dn is an abbreviation for domain. Only a X few of these are used in the entire Applications group; X X X X X X X X X X X X X an example of a plausible use is given in the discus- X sion of e, below. X X Xe an element of an array. This is used in conjunction X with a dn (and is thus just as rare); it is the type of X the value stored in a dn. Just as rgx is equivalent to X mpixx, dnx is equivalent to mpxex. An example of use X is the native code generation part of the CS compiler; X there is a type vr (an acronym for virtual register). X A vr is just a simple integer, specifying which regis- X ter to use for various pieces of code output. However, X there is quite a bit more information than just a X number that is associated with each register. This X additional data is stored in a structure called an evr; X there is an array of them called dnvr. Thus, the X information for a given register can be found with the X expression dnvr[vr]. X X Xf a bit within a type. This is a new prefix that is X currently used only by a few projects, but is now the X approved method for dealing with bits. It is typically X used for overloading an integer type with one or more X bit flags, in otherwise unused portions of the integer. X This should not be confused with the f type, in which X the entire value is used to contain the flag. An exam- X ple is a scan mode (type sm), with possible values X smForward and smBackwards. Since the basic mode only X requires a few bits (in this case only one bit), the X remainder of a word can be used to encode other infor- X mation. One bit is used for fsmWrap, another for X fsmCaseInsens. Here the f is a prefix to the sm type, X specifying only a single bit is used. X X Xsh a shift amount. This is another new prefix used to X deal with bits within other types (complementing the X "f" prefix); it specifies the location within the type X by a bit number (rather than the bit mask which the "f" X prefix specifies). It actually is followed by two X types; the first type is the type being shifted (almost X always an f), and the second type is the type the bits X are stored within. Continuing the above example of X scan modes, if fsmWrap has a value of 4000 hex, X shfsmWrap would have the value of 14. X X Xu a union. This is a rarely used prefix; it is used for X variables that can hold one of several types. In prac- X tice this becomes unwieldy. An example is a urwcol, X which can hold either a rw type or a col type. X X X X X X X X X X X X X X Xa an allocation. This is a rarely used prefix; it is X used to distinguish between an array and a pointer to X it. Thus, sz is a pointer to a null-terminated string X and asz is the actual allocated space. a is almost X invariably used in conjunction with a pointer-type pre- X fix, in order to allow the pointer to be explicit X (rather than implicit, as with an sz). It is essen- X tially the inverse of a p prefix, so pasz is equivalent X to sz. Its best use is with the h prefix; hasz is a X handle to a null-terminated string. Most of the X current Applications code (incorrectly) omits the a. X X Xv A global variable X X X X2.1.2.1. 2.1.2.1.Some Examples X X XSince the prefixes and base types both appear in lower case, Xwith no separating punctuation, ambiguity can arise. Is pfc Xa tag of its own (e.g., for a private first class), or is it Xa pointer to an fc? Such questions can be answered only if Xone is familiar with the specific types used in a program. XTo avoid problems like this it is often wise to avoid creat- Xing base type names that begin with any of the common pre- Xfixes. In practice, ambiguity does not seem to be a prob- Xlem. The idea of additional punctuation to remove the ambi- Xguity has been shown to be impractical. X X XThe following list contains both common and rarer usages: X X X Xpch a pointer to a character. X X Xich an index into an array of character. X X Xrgst an array of Pascal-type strings. Hungarian is X not sufficient in itself to indicate whether X this is an array of characters or an array of X pointers; since strings are usually variable X length, it is probably a safe bet that this is X an array of pointers to the actual characters. X X Xgrst a group of Pascal-type strings. As with the X above example, this could be either an array of X characters or of pointers; since it is a gr, not X an rg, it is probably safe to assume that it is X X X X X X X X X X X X X an array of characters. X X Xbst an offset to a particular Pascal-type string in X a grst. X Xphpx a near pointer to a huge pointer to an object of X type x. X X Xpich a near pointer to an index into a character X array. A common use for something like this is X passing a pointer as a parameter to a function X so that a return value can be stored through the X pointer; pich would be extremely unlikely to be X used in an expression without indirection X (pich+=2 is probably gibberish; (*pich)+=2 may X well be meaningful). X X Xen probably a base type (such as an entry). Con- X ceivably it is an element for an array indexed X by an n; only knowledge of the application can X tell for certain. X X Xhrgn handle to a region. Again there is ambiguity; X this could be interpreted as a handle to an X array of n's or a huge pointer to an array of X n's. X X Xdx length of a horizontal line (difference between X x coordinates). X X Xrgrgx a two-dimensional array of x's (an array of X arrays of x's). X X Xmpminpfn an array of pointers to functions, indexed by X mi's. For example, an mi could be a menu item, X and this array could be used for a command X dispatch. Again, context makes the parsing X clear; this could equally well be interpreted as X an array of fn's (perhaps friendly nukes), X indexed by mip's (perhaps missile placements). X X Xpv pointer to a void. Could be used as an argument X to Free. X X Xhrgch huge pointer to an array of characters. Could X X X X X X X X X X X X X instead be interpreted as a handle to an array X of characters, depending on the application. X X X X2.1.3. X2.1.3.Qualifiers X X XWhile the prefixes and base type are sufficient to fully Xspecify the type of a variable, this may not be sufficient Xto distinguish the variable. If there are two variables of Xthe same type within the same context, further specification Xis required to disambiguate. This is done with qualifiers. XA qualifier is a short descriptive word (or facsimile; good XEnglish is not required) that indicates what the variable is Xused for. In some cases, multiple words may be used. Some Xdistinctive punctuation should be used to separate the qual- Xifier from the type; in C and other languages that support Xit, this is done by making the first letter of the qualifier Xupper-case. (If multiple words are used, the first letter Xof each should be upper-case; the remainder of the name, Xboth type and qualifier, is always lower-case. There is one Xspecial case to watch out for; defined constants specifying Xthe size of a type are often of the form cbFOO or cwFOO, Xwhere foo is the type. Strictly speaking only the F in FOO Xshould be capitalized, but the incorrect usage is fairly Xcommon.) X X XExactly what constitutes a naming context is language Xspecific; within C the contexts are individual blocks (com- Xpound statements), procedures, data structures (for naming Xfields), or the entire program (globals). As a matter of Xgood programming style, it is not recommended that hiding of Xnames be used; this means that any context should be con- Xsidered to include all of its subcontexts. (In other words, Xdon't give a local the same name as a global.) If there is Xno conflict within a given context (only one variable of a Xgiven type), it is not necessary to use a qualifier; the Xtype alone serves to identify the variable. In small con- Xtexts (data structures or small procedures), a qualifier Xshould not be used except in case of conflict; in larger Xcontexts it is often a good idea to use a qualifier even Xwhen not necessary, since later modification of the code may Xmake it necessary. In cases of ambiguity, one of the vari- Xables may be left with no qualifier; this should only be Xdone if it is clearly more important than the other vari- Xables of the same type (no qualifier implies primary usage). X X XSince many uses of variables fall into the same basic Xcategories, there are several standard qualifiers. If Xapplicable, one of these should be used, since they specify X X X X X X X X X X X X Xmeaning with no chance of confusion. In the case of multi- Xple word qualifiers, the order of the words is not crucial, Xand should be chosen for clarity; if one of the words is a Xstandard qualifier, it should probably come last (unfor- Xtunately, this suggestion is by no means uniformly fol- Xlowed). The standard qualifiers are: X X X XFirst the first element in a set. This is usually X used with an index or a pointer (e.g., X pchFirst), referring to the first element of an X array to be dealt with. The index may be an X implied index (as with a rw type in a X spreadsheet). X X XLast the last element in a set. This is usually used X with an index or a pointer (e.g., pchLast), X referring to the last element of an array to be X dealt with). Both First and Last represent X valid values (compare with Lim below); they are X often paired, as in this common loop: for X (ich=ichFirst; ich<=ichLast; ich++) X X XLim the upper limit of elements in a set. This is X not a valid value; for all valid values f x, X x&2 if test -f hungqr.mm ; then echo "will not overwrite hungqr.mm" 1>&2 else sed 's/^X//' > hungqr.mm <<\!!!EOF!!! X.\" eroff -mm %s X.\" $Id: hungqr.mm,v 1.7 90/10/15 09:44:46 billc Exp Locker: billc $ X.nr Cl 3 X.TL "" "" XHUNGARIAN NAMING CONVENTIONS QUICK REFERENCE X.br X\!.br X.sp XFederal Emergency Management Agency (FEMA) X.br X\!.br XIntegrated Emergency Management Information System (IEMIS) X.AF "Battelle Pacific Northwest Laboratory" X.AU "D. E. Buska" X.AU "J. J. Jou" X.AU "W. K. Campbell" X.AS 1 XThis is a quick reference guide for a modified version of the XHungarian naming conventions described in the paper X.I XHungarian Naming Conventions X.R Xby Doug Klunder of Microsoft. These conventions have been adapted Xby the authors for the IEMIS project. XThe primary purpose for adopting this notation is to achieve a Xconsistent coding standard project-wide. XWhen a project involves more than a half-dozen people with differing Xlevels of expertise, it is important for every individual to be able Xto read others' code in a fairly familiar format, to facilitate Xmaintenance and understanding efficiently. XHungarian notation, when employed correctly, offers an immediately Xrecognizable connection between an object, its data type and its Xintended purpose. XIt is expected that these benfits will outweigh the inconvenience of Xlearning and using the notation. X.P X\*(DT X.AE X.MT 4 X.PH "'Hungarian Quick Reference''Printed \*(DT'" X.PF "''Page %''" X.H 1 General XIdentifier names in the hungarian convention consists of: X.DS C N X.ft CW X[] X.ft X.DE X.P Xwhere \f(CWbasetype\fR indicates the data type represented by the identifier. XThe \f(CWprefix\fR clarifies the basetype, if necessary. XThe basetype and the prefix are in all lowercase. X\f(CWQualifier\fR is a descriptive word or compound word indicating the Xspecific usage of the identifier. XThe first letter of the qualifier is uppercase, and Xsubsequent words of a compound word qualifier are first letter uppercase. X.H 1 "Usage Rules" XIn the following rules, optional components are enclosed in [brackets], and Xcase is significant (i.e. if the component name is in uppercase, the component Xshould be in uppercase, and so on). X.H 2 Variable Xmust have the form: X\f(CW[][]\fR X.H 2 "\f(CW#define\fRd Constants" Xmust have the form: X\f(CW\fR X.H 2 "Procedure Names" Xmust have the form: X\f(CW\fR X.H 2 "Macros" Xmust have the form: X\f(CW\fR X.H 2 "Global Variables" Xmust have an additional prefix of ``\f(CWv\fR'' X.H 2 "Static Variables" Xmust have an additional prefix of ``\f(CWy\fR'' X.H 2 "Single Character Names" XThe use of single character name, such as \f(CWi\fR, is discouraged since Xit does not conform to the basic variable naming rule. X.H 2 "User-defined Types" XThe name of a user defined (\f(CWtypedef\fR) data type shall be all in Xuppercase, and shall end in ``\f(CWTYPE\fR'' (e.g. \f(CWVECTORTYPE\fR). XA variable of this type has a \f(CWt\fR prefix. X.H 1 "Standard Basetypes" X.VL 10 X.LI \f(CWf\fR Xa flag. X.LI \f(CWch\fR Xa one byte character. X.LI \f(CWst\fR Xa string that contains the length of the string in the first Xbyte. This type of string can only handle up to 256 bytes. X.LI \f(CWsz\fR Xa null-terminated string. X.LI \f(CWfn\fR Xa function. X.LI \f(CWfl\fR Xpointer to a type of FILE. X.LI \f(CWi\fR Xan integer. Use of this type shall be limited because the Xinteger type is represented differently on different systems. X.LI \f(CWs\fR Xa signed short integer. X.LI \f(CWus\fR Xa unsigned short integer. X.LI \f(CWl\fR Xa signed long integer. X.LI \f(CWul\fR Xa unsigned long integer. X.LI \f(CWb\fR Xa 8 bits byte data. X.LI \f(CWd\fR Xa double precision real number. X.LI \f(CWr\fR Xa single precision real number. X.LI \f(CWv\fR Xa void data type. X.LI \f(CWbit\fR Xa single bit data. X.LI \f(CWp\fR Xa pointer, always a 32 bit address. X.LI \f(CWt\fR Xa user defined (\f(CWtypedef\fR) type, usually a \f(CWstruct\fR. X.LI \f(CWw\fR Xan X Window System (or Motif) widget. X.LI \f(CWu\fR Xa union. X.LI \f(CWxy\fR Xa 2D coordinate point type. X.LI \f(CWdim\fR Xa 2D dimension type; used for specifying width and length. X.LE X.H 1 "Standard Prefixes" X.VL 10 X.LI \f(CWv\fR Xa global variable. X.LI \f(CWi\fR Xan index into an array. \f(CWich\fR would be an index to a character Xarray (string). \f(CWifl\fR would be the offset of a file location. X.LI \f(CWc\fR Xa count of something. \f(CWcch\fR would be the count of the characters Xin a character array (string). \f(CWcfl\fR would be the file size. X.LI \f(CWd\fR Xa difference between two instances of a type. \f(CWdich\fR would be Xthe number of characters between two \f(CWich\fR's. X.LI \f(CWh\fR Xa pointer to a pointer. \f(CWhsz\fR would be the pointer to a Xnull-terminated string. This prefix is strictly for a true pointer. XHence \f(CWhsz[ich][ich]\fR, for example, is considered illegal. X.LI \f(CWu\fR Xan union that can represent different types. \f(CWurwcol\fR would Xhold either a row or column value if \f(CWrw\fR and \f(CWcol\fR are defined types. X.LI \f(CWa\fR Xan allocation. used to distinguish an array and a pointer to it. X\f(CWasz\fR would be a string buffer rather than a possible pointer to a Xstring. This prefix may be used when a clear distinction between Xa array and a pointer to it is desired. X.LI \f(CWrg\fR Xan array. Some examples: X.LI \f(CWrgch\fR Xis an array of characters which is not always Xnull terminated. For a guaranteed null-terminated Xcharacter array (C string), use \f(CWsz\fR data type. XThe index to it would be \f(CWich\fR. X.LI \f(CWrgsz\fR Xis an array of null terminated strings. The index to it would be \f(CWisz\fR. X.LI \f(CWgr\fR Xa group. X.P XThis prefix is different from \f(CWrg\fR in that its use is for variable length Xobjects. For example, one may allocate a buffer that stores a set of Xvector objects. Because vector object has may different types, for each Xtype encountered in the buffer, there is some information used to Xindicate the size of the current vector object type. This buffer Xcan be represented by \f(CWgrvec\fR, where \f(CWvec\fR is a user defined Xbase type. XThis usage also suggests that index to a \f(CWgr\fR type is meaningless. XRather, the offset prefix should be used in this case. X.P XAnother example, consider a string that contains a series of Xnull-terminated strings. This type of string can be represented Xby \f(CWgrsz\fR, a group of null-terminated strings. Again an index Xto this type is not meaningful because each `element' has to be Xaccessed through an unique method. Therefore offset prefix Xshould be used for a \f(CWgr\fR type of data object. X.LI \f(CWmp\fR Xan array. XThis prefix is limited to cases that the types of Xthe indices and value stored in the array are important. XOtherwise \f(CWrg\fR should be used. \f(CWmp\fR must be followed by the types Xof the array dimensions (x,y,z in exact order) then the type of Xthe value stored in the array. X.LI \f(CWo\fR Xan offset. XThis prefix is limited to use in conjunction with Xa \f(CWgr\fR type. An exception to this is that this prefix can be used Xfor a offset of a file pointer. Strictly speaking, a file Xis a \f(CWgr\fR type in some sense because a file contains a series of Xrecords that are often in variable length. Hence, \f(CWofl\fR would be Xthe offset of a file pointer relative to the reference base. X.LI \f(CWb\fR Xa bit with a type. \f(CWblX\fR would be some sort of bit(s) value of Xthe x object that is of long type. X.LE X.H 1 "Standard Qualifiers" XThe following standard qualifiers may be used: X\f(CWFirst, Last, Min, Max, Mac, Mic, Sav, Nil, T, Src, Dest\fR. XPlease observe the following strict relationship: X.DS C N X.ft CW XMin <= Mic <= First <= Last < Mac <= Max. X.ft X.DE X.VL 10 X.LI \f(CWFirst\fR Xthe actual first element in a set. X.LI \f(CWLast\fR Xthe actual last element in a set. X.LI \f(CWMax\fR Xthe upper limit of elements of a set. X.LI \f(CWMin\fR Xthe lower limit of elements of a set. X.LI \f(CWMac\fR Xthe current upper limit of elements in a set. X.LI \f(CWMic\fR Xthe current lower limit of elements in a set. X.LI \f(CWSav\fR Xa temporary save value. X.LI \f(CWNil\fR Xa invalid value. X.LI \f(CWT\fR Xa temporary value. When there is no ambiguity, \f(CWT1, T2,\fR etc may Xbe used to represent temporary values. X.LI \f(CWSrc\fR Xa source. X.LI \f(CWDest\fR Xa destination. X.LE X.H 1 "Examples" XHere are some examples of hungarian prefix and base type usage: X.VL 18 X.LI \f(CWpch\fR Xa pointer to a character. X.LI \f(CWich\fR Xan index into an array of character. X.LI \f(CWrgst\fR Xan array of Pascal-type strings. Hungarian is not sufficient in Xitself to indicate whether this is an array of characters or an Xarray of pointers; since strings are usually variable length, it is Xprobably a safe bet that this is an array of pointers to the actual Xcharacters. X.LI \f(CWgrst\fR Xa group of Pascal-type strings. As with the above example, this Xcould be either an array of characters or of pointers; since it is Xa \f(CWgr\fR, not an \f(CWrg\fR, it is probably safe to assume that it Xis an array of characters. X.LI \f(CWbst\fR Xan offset to a particular Pascal-type string in a \f(CWgrst\fR. X.LI \f(CWphpx\fR Xa near pointer to a huge pointer to an object of type \f(CWx\fR. X.LI \f(CWpich\fR Xa near pointer to an index into a character array. A common use Xfor something like this is passing a pointer as a parameter to a Xfunction so that a return value can be stored through the pointer; Xpich would be extremely unlikely to be used in an expression without Xindirection [\f(CWpich+=2\fR is probably gibberish; \f(CW(*pich)+=2\fR Xmay well be meaningful]. X.LI \f(CWen\fR Xprobably a base type (such as an entry). Conceivably it is an Xelement for an array indexed by an \f(CWn\fR; only knowledge of the Xapplication can tell for certain. X.LI \f(CWhrgn\fR Xhandle to a region. Again there is ambiguity; this could be Xinterpreted as a handle to an array of \f(CWn\fR's or a huge pointer to an Xarray of \f(CWn\fR's. X.LI \f(CWdx\fR Xlength of a horizontal line (difference between \f(CWx\fR coordinates). X.LI \f(CWrgrgx\fR Xa two-dimensional array of \f(CWx\fR's (an array of arrays of \f(CWx\fR's). X.LI \f(CWmpminpfn\fR Xan array of pointers to functions, indexed by \f(CWmi\fR's. For Xexample, an mi could be a menu item, and this array could be Xused for a command dispatch. Again, context makes the parsing Xclear; this could equally well be interpreted as an array of X\f(CWfn\fR's (perhaps friendly nukes), indexed by mip's (perhaps Xmissile placements). X.LI \f(CWpv\fR Xpointer to a void. Could be used as an argument to \f(CWfree()\fR. X.LI \f(CWhrgch\fR Xhuge pointer to an array of characters. Could instead be Xinterpreted as a handle to an array of characters, depending Xon the application. X.P XHere are some examples of IEMIS-specific identifiers: X.LI \f(CWpchExpCharPtr\fR Xa pointer to a character declared in the Exception Handling module. X.LE X.CS X.TC !!!EOF!!! if [ "`wc -c hungqr.mm`" -ne " 10803 hungqr.mm" ] then echo \07WARNING hungqr.mm: extraction error fi fi echo Extracting hungqr.ascii... 1>&2 if test -f hungqr.ascii ; then echo "will not overwrite hungqr.ascii" 1>&2 else sed 's/^X//' > hungqr.ascii <<\!!!EOF!!! X X X X HUNGARIAN NAMING CONVENTIONS QUICK REFERENCE X X Federal Emergency Management Agency (FEMA) X Integrated Emergency Management Information System (IEMIS) X X D. E. Buska X X J. J. Jou X X W. K. Campbell X X Battelle Pacific Northwest Laboratory X X X 1. General X X Identifier names in the hungarian convention consists of: X X [] X X where basetype indicates the data type represented by the X identifier. The prefix clarifies the basetype, if X necessary. The basetype and the prefix are in all lowercase. X Qualifier is a descriptive word or compound word indicating X the specific usage of the identifier. The first letter of X the qualifier is uppercase, and subsequent words of a X compound word qualifier are first letter uppercase. X X X 2. Usage_Rules X X In the following rules, optional components are enclosed in X [brackets], and case is significant (i.e. if the component X name is in uppercase, the component should be in uppercase, X and so on). X X 2.1 Variable X X must have the form: [][] X X 2.2 #defined Constants X X must have the form: X X 2.3 Procedure_Names X X must have the form: X X 2.4 Macros X X must have the form: X X X X X X X X Page 1 X X X X X X X X Hungarian Quick Reference Printed November 20, 1990 X X X X 2.5 Global_Variables X X must have an additional prefix of ``v'' X X 2.6 Static_Variables X X must have an additional prefix of ``y'' X X 2.7 Single_Character_Names X X The use of single character name, such as i, is discouraged X since it does not conform to the basic variable naming rule. X X 2.8 User-defined_Types X X The name of a user defined (typedef) data type shall be all X in uppercase, and shall end in ``TYPE'' (e.g. VECTORTYPE). X A variable of this type has a t prefix. X X X 3. Standard_Basetypes X X f a flag. X X ch a one byte character. X X st a string that contains the length of the string in X the first byte. This type of string can only X handle up to 256 bytes. X X sz a null-terminated string. X X fn a function. X X fl pointer to a type of FILE. X X i an integer. Use of this type shall be limited X because the integer type is represented X differently on different systems. X X s a signed short integer. X X us a unsigned short integer. X X l a signed long integer. X X ul a unsigned long integer. X X b a 8 bits byte data. X X X X X X Page 2 X X X X X X X X Hungarian Quick Reference Printed November 20, 1990 X X X X d a double precision real number. X X r a single precision real number. X X v a void data type. X X bit a single bit data. X X p a pointer, always a 32 bit address. X X t a user defined (typedef) type, usually a struct. X X w an X Window System (or Motif) widget. X X u a union. X X xy a 2D coordinate point type. X X dim a 2D dimension type; used for specifying width and X length. X X X 4. Standard_Prefixes X X v a global variable. X X i an index into an array. ich would be an index to X a character array (string). ifl would be the X offset of a file location. X X c a count of something. cch would be the count of X the characters in a character array (string). cfl X would be the file size. X X d a difference between two instances of a type. X dich would be the number of characters between two X ich's. X X h a pointer to a pointer. hsz would be the pointer X to a null-terminated string. This prefix is X strictly for a true pointer. Hence hsz[ich][ich], X for example, is considered illegal. X X u an union that can represent different types. X urwcol would hold either a row or column value if X rw and col are defined types. X X a an allocation. used to distinguish an array and a X pointer to it. asz would be a string buffer rather X than a possible pointer to a string. This prefix X may be used when a clear distinction between a X X X X Page 3 X X X X X X X X Hungarian Quick Reference Printed November 20, 1990 X X X X array and a pointer to it is desired. X X rg an array. Some examples: X X rgch is an array of characters which is not always null X terminated. For a guaranteed null-terminated X character array (C string), use sz data type. The X index to it would be ich. X X rgsz is an array of null terminated strings. The index X to it would be isz. X X gr a group. X X This prefix is different from rg in that its use X is for variable length objects. For example, one X may allocate a buffer that stores a set of vector X objects. Because vector object has may different X types, for each type encountered in the buffer, X there is some information used to indicate the X size of the current vector object type. This X buffer can be represented by grvec, where vec is a X user defined base type. This usage also suggests X that index to a gr type is meaningless. Rather, X the offset prefix should be used in this case. X X Another example, consider a string that contains a X series of null-terminated strings. This type of X string can be represented by grsz, a group of X null-terminated strings. Again an index to this X type is not meaningful because each `element' has X to be accessed through an unique method. X Therefore offset prefix should be used for a gr X type of data object. X X mp an array. This prefix is limited to cases that the X types of the indices and value stored in the array X are important. Otherwise rg should be used. mp X must be followed by the types of the array X dimensions (x,y,z in exact order) then the type of X the value stored in the array. X X o an offset. This prefix is limited to use in X conjunction with a gr type. An exception to this X is that this prefix can be used for a offset of a X file pointer. Strictly speaking, a file is a gr X type in some sense because a file contains a X series of records that are often in variable X length. Hence, ofl would be the offset of a file X pointer relative to the reference base. X X X X X Page 4 X X X X X X X X Hungarian Quick Reference Printed November 20, 1990 X X X X b a bit with a type. blX would be some sort of X bit(s) value of the x object that is of long type. X X X 5. Standard_Qualifiers X X The following standard qualifiers may be used: First, Last, X Min, Max, Mac, Mic, Sav, Nil, T, Src, Dest. Please observe X the following strict relationship: X X Min <= Mic <= First <= Last < Mac <= Max. X X First the actual first element in a set. X X Last the actual last element in a set. X X Max the upper limit of elements of a set. X X Min the lower limit of elements of a set. X X Mac the current upper limit of elements in a set. X X Mic the current lower limit of elements in a set. X X Sav a temporary save value. X X Nil a invalid value. X X T a temporary value. When there is no ambiguity, X T1, T2, etc may be used to represent temporary X values. X X Src a source. X X Dest a destination. X X X 6. Examples X X Here are some examples of hungarian prefix and base type X usage: X X pch a pointer to a character. X X ich an index into an array of character. X X rgst an array of Pascal-type strings. X Hungarian is not sufficient in itself to X indicate whether this is an array of X characters or an array of pointers; since X strings are usually variable length, it is X X X X Page 5 X X X X X X X X Hungarian Quick Reference Printed November 20, 1990 X X X X probably a safe bet that this is an array X of pointers to the actual characters. X X grst a group of Pascal-type strings. As with X the above example, this could be either an X array of characters or of pointers; since X it is a gr, not an rg, it is probably safe X to assume that it is an array of X characters. X X bst an offset to a particular Pascal-type X string in a grst. X X phpx a near pointer to a huge pointer to an X object of type x. X X pich a near pointer to an index into a X character array. A common use for X something like this is passing a pointer X as a parameter to a function so that a X return value can be stored through the X pointer; pich would be extremely unlikely X to be used in an expression without X indirection [pich+=2 is probably X gibberish; (*pich)+=2 may well be X meaningful]. X X en probably a base type (such as an entry). X Conceivably it is an element for an array X indexed by an n; only knowledge of the X application can tell for certain. X X hrgn handle to a region. Again there is X ambiguity; this could be interpreted as a X handle to an array of n's or a huge X pointer to an array of n's. X X dx length of a horizontal line (difference X between x coordinates). X X rgrgx a two-dimensional array of x's (an array X of arrays of x's). X X mpminpfn an array of pointers to functions, indexed X by mi's. For example, an mi could be a X menu item, and this array could be used X for a command dispatch. Again, context X makes the parsing clear; this could X equally well be interpreted as an array of X fn's (perhaps friendly nukes), indexed by X mip's (perhaps missile placements). X X X X Page 6 X X X X X X X X Hungarian Quick Reference Printed November 20, 1990 X X X X pv pointer to a void. Could be used as an X argument to free(). X X hrgch huge pointer to an array of characters. X Could instead be interpreted as a handle X to an array of characters, depending on X the application. X X Here are some examples of IEMIS-specific X identifiers: X X pchExpCharPtr a pointer to a character declared in the X Exception Handling module. X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X Page 7 X X X X X X X X X X HUNGARIAN NAMING CONVENTIONS QUICK REFERENCE X X Federal Emergency Management Agency (FEMA) X Integrated Emergency Management Information System (IEMIS) X X D. E. Buska X X J. J. Jou X X W. K. Campbell X Battelle Pacific Northwest Laboratory X X X ABSTRACT X X X X This is a quick reference guide for a modified version of X the Hungarian naming conventions described in the paper X Hungarian Naming Conventions by Doug Klunder of Microsoft. X These conventions have been adapted by the authors for the X IEMIS project. The primary purpose for adopting this X notation is to achieve a consistent coding standard X project-wide. When a project involves more than a half-dozen X people with differing levels of expertise, it is important X for every individual to be able to read others' code in a X fairly familiar format, to facilitate maintenance and X understanding efficiently. Hungarian notation, when X employed correctly, offers an immediately recognizable X connection between an object, its data type and its intended X purpose. It is expected that these benfits will outweigh X the inconvenience of learning and using the notation. X X November 20, 1990 X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X CONTENTS X X X 1. General.............................................. 1 X X 2. Usage Rules.......................................... 1 X 2.1 Variable........................................ 1 X 2.2 #defined Constants.............................. 1 X 2.3 Procedure Names................................. 1 X 2.4 Macros.......................................... 1 X 2.5 Global Variables................................ 2 X 2.6 Static Variables................................ 2 X 2.7 Single Character Names.......................... 2 X 2.8 User-defined Types.............................. 2 X X 3. Standard Basetypes................................... 2 X X 4. Standard Prefixes.................................... 3 X X 5. Standard Qualifiers.................................. 5 X X 6. Examples............................................. 5 X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X X - i - X X X X !!!EOF!!! if [ "`wc -c hungqr.ascii`" -ne " 15673 hungqr.ascii" ] then echo \07WARNING hungqr.ascii: extraction error fi fi echo Extracting iemis.m4... 1>&2 if test -f iemis.m4 ; then echo "will not overwrite iemis.m4" 1>&2 else sed 's/^X//' > iemis.m4 <<\!!!EOF!!! Xdefine(M4RCSID,$Header: /disk1/d3c962/iemis/iemis.m4,v 1.1 90/04/11 14:57:39 d3c962 Exp $) Xdefine(PROJECT_NAME,IEMIS) Xdefine(PROJECT_FULL_NAME,Integrated Emergency Management Information System) Xdefine(ORGANIZATION_NAME,Pacific Northwest Laboratory) Xdefine(VERSION_NUMBER,4.0) Xdefine(ADDITIONAL_VERIFICATION_FUNCTION,CodeCheck) Xdefine(LINE_SPACING,1) Xdefine(ECP_USER_TITLES,PROJECT_NAME Developers) !!!EOF!!! if [ "`wc -c iemis.m4`" -ne " 399 iemis.m4" ] then echo \07WARNING iemis.m4: extraction error fi fi echo Extracting iemis.tmac... 1>&2 if test -f iemis.tmac ; then echo "will not overwrite iemis.tmac" 1>&2 else sed 's/^X//' > iemis.tmac <<\!!!EOF!!! X.\" $Header: /disk2/d3c962/iemis/RCS/imac.ms,v 1.3 90/07/13 10:30:15 d3c962 Exp $ X.\" .so /usr/lib/ms/ms.toc X.nr C1 3 X. \"B - turn on bold X.RP no X.de B X.ft B X.it 1 }N X.if !"\\$1"" \&\\$1 \\$2 \\$3 \\$4 \\$5 \\$6 X.. X. \"NH - numbered heading X.de NH X.RT X.if \\n(1T .sp 1 X.if !\\n(1T .BG X.RT X.ne 4 X.ft 3 X.if n .ul 1000 X.nr NS \\$1 X.if !\\n(.$ .nr NS 1 X.if !\\n(NS .nr NS 1 X.nr H\\n(NS +1 X.if !\\n(NS-4 .nr H5 0 X.if !\\n(NS-3 .nr H4 0 X.if !\\n(NS-2 .nr H3 0 X.if !\\n(NS-1 .nr H2 0 X.if !\\$1 .if \\n(.$ .nr H1 1 X.ds SN \\n(H1. X.ti \\n(.iu X.if \\n(NS-1 .as SN \\n(H2. X.if \\n(NS-2 .as SN \\n(H3. X.if \\n(NS-3 .as SN \\n(H4. X.if \\n(NS-4 .as SN \\n(H5. X.as SN \ \ X.. X.\" Heading Level 1 X.de 1H X.NH 1 X.as SN \\$1\ X.as SN \\$2\ X.as SN \\$3\ X.as SN \\$4\ X.as SN \\$5\ X.as SN \\$6\ X.as SN \\$7\ X.as SN \\$8\ X.as SN \\$9\ X.XS X\\*(SN X.XE X.B X\\*(SN X.. X.\" Heading Level 2 X.de 2H X.NH 2 X.as SN \\$1\ X.as SN \\$2\ X.as SN \\$3\ X.as SN \\$4\ X.as SN \\$5\ X.as SN \\$6\ X.as SN \\$7\ X.as SN \\$8\ X.as SN \\$9\ X.XS X\\*(SN X.XE X.B X\\*(SN X.. X.\" Heading Level 3 X.de 3H X.NH 3 X.as SN \\$1\ X.as SN \\$2\ X.as SN \\$3\ X.as SN \\$4\ X.as SN \\$5\ X.as SN \\$6\ X.as SN \\$7\ X.as SN \\$8\ X.as SN \\$9\ X.XS X\\*(SN X.XE X.B X\\*(SN X.. X.\" Heading Level 4 X.de 4H X.NH 4 X.as SN \\$1\ X.as SN \\$2\ X.as SN \\$3\ X.as SN \\$4\ X.as SN \\$5\ X.as SN \\$6\ X.as SN \\$7\ X.as SN \\$8\ X.as SN \\$9\ X.B X\\*(SN X.. X.\" Heading Level 5 X.de 5H X.NH 5 X.as SN \\$1\ X.as SN \\$2\ X.as SN \\$3\ X.as SN \\$4\ X.as SN \\$5\ X.as SN \\$6\ X.as SN \\$7\ X.as SN \\$8\ X.as SN \\$9\ X.B X\\*(SN X.. !!!EOF!!! if [ "`wc -c iemis.tmac`" -ne " 1566 iemis.tmac" ] then echo \07WARNING iemis.tmac: extraction error fi fi