|
Coding Style
To simplify the documentation, GenoPro uses a subset of the
Hungarian Notation. The Hungarian naming convention adds a prefix to the
identifier name to indicate its functional type. For instance, an index will be
prefixed with the letter i, a counter will be prefixed with the
letter
c, and a string with the prefix str. The following
table displays a summary of the primitive data types:
| Prefix |
Description |
i |
Index. An index is a zero-based
number to access an item in a collection. The first item of the
collection is at the index 0. Please notice GenoPro may use the letter
i
for an individual and f for a family as the
loop item
name.
Example:
iChildFirst = 0 ' First
child in the collection
iChildLast = i.children.count - 1 |
c |
Count. A count is a number to indicate the total of
number of items, rather than its position within the collection as the
index does.
Example:
cChildren = i.children.count '
Get the number of children |
| n |
Number. This is when a number is not an index nor a
counter.
Example:
nErrorCode = 5 ' Access
denied (according to the Win32 error codes)
nYearOfBirth = i.birth.year |
str |
String. Any sequence of characters such as a name,
comment or description.
Example:
strNameFirst = i.name.first
' Get the first name of the individual |
ch |
A single character. This is rarely used by the report
generator but can be useful to indicate the presence of a single
character. For instance, the component
chEncoding from method
Util.FormatString
designates the encoding of the string represented by a single character
such as t, x or u. |
o |
Object. Any complex data structure such as dictionary,
repertory, collection. You may consider as an object a picture,
individual, family, pedigree link, however it is recommended to define a
special prefix for each. For the report generator, everything is an
object, so use the o prefix as a "catch all" when there is
no better appropriate prefix to use. For instance, if you are
manipulating several pictures, you may consider using the prefix
pic instead of o for a picture object. This
way, the variable name picFather and picMother
will be more descriptive and less confusing than oPictureFather
and oPictureMother.
Examples:
Set oDictionary =
Util.NewStringDictionary()
Set oChildFirst = i.children(0)
' Get the first child |
f |
Boolean flag. This variable indicates the presence of a
boolean value such as true or false. A boolean value is not useful to
the end user reading the report, however can be very useful to store
intermediate results of conditional expressions. The intuitive prefix
for a boolean value would be the letter b, however GenoPro
uses the b prefix for a byte. Since the report generator
does not manipulate bytes, this prefix is not documented here.
Example:
fDisplayPictures =
i.Pictures.count > 0 |
The report generator uses the Session object
as a data repertory to store and retrieve objects between HTML pages. Since the
session can store anything from a string to a number to a complex object, the
key of the session uses a prefix of the data it contains. Here are a few
examples:
Session("strTitleReport") = "My Report"
Session("fIncludePictureAlbum") = true
Set oDictionary = Util.NewStringDictionary()
Session("oDictionaryUniqueLastNames") = oDictionary
Variable and Routine Naming
When in doubt, GenoPro names the variables to favor sorting, so
similar variables and routines can be easily grouped together, thus making it
easier to find a resembling routine. For instance, the VBScript language has
tree routines for trimming spaces: Trim, LTrim and
RTrim. GenoPro would have named those routines Trim,
TrimLeft
and TrimRight respectively, so the user can quickly discover the
presence of routines to trim left and right. Similarly, GenoPro uses the name
strNameFirst, so the variable can be grouped with other similar variables
such as strNameMiddle and strNameLast. Using
strFirstName, strMiddleName, and strLastName
may be a bit easier to read, however those variables would be more difficult to
find using a code browser. Most development environment have tools to browse
through code, and the most popular practice is to display all variables and
routines sorted alphabetically. In the case of the report generator, there is no
such thing as a code browser, however the documentation of the report generator
uses the same coding practices as GenoPro does for writing the C++ code.
Hungarian Notation History
Long time ago,
Charles
Simonyi introduced a naming convention that adds a prefix to the identifier
name to indicate the functional type of the identifier. This system became
widely used inside Microsoft. It came to be known as "Hungarian Notation"
because the prefixes make the variable names look a bit as though they're
written in some non-English language and because Simonyi is originally from
Hungary.
As it turns out, the Hungarian naming convention is quite useful—it's one
technique among many that helps programmers produce better code faster.
GenoPro uses the Hungarian notation intensively. GenoPro extended the original
Hungarian notation to include more data types and functionalities. GenoPro has a
20-page document describing notations for classes, interfaces, methods, member
variables, static variables, global variables, objects, arrays, bitwise
operations, memory allocation cycles, error handling, exception handling, and
data flow to name a few.
There are many other benefits of using the Hungarian notation such as finding
bugs at compile time and finding bugs during code reviews. People rejecting the
usefulness of the Hungarian notation never grasped the idea of using the
compiler as a debugger.
|