hungnote.txt

国外网站上的一些精典的C程序

***********

Program Identifier Naming Conventions

  This monograph is intended to give you the flavor of the major ideas behind
the conventions.

  When confronted with the need for a new name in a program, a good
programmer will generally consider the following factors to reach a decision:

  1.  Mnemonic value - so that the programmer can remember the name.
  2.  Suggestive value - so that others can read the code.
  3.  "Consistency" - this is often viewed as an aesthetic idea, yet it also
      has to do with the information efficiency of the program text.  Roughly
      speaking, we want similar names for similar quantities.
  4.  Speed of the decision - we cannot spend too much time pondering the
      name of a single quantity, nor is there time for typing and editing
      extremely long variable names.

  All in all, name selection can be a frustrating and time consuming subtask.
Often, a name which satisfies some of the above criteria will contradict the
others. Maintaining consistency can be especially difficult.


Advantages of the Conventions

  The following naming conventions provide a very convenient framework for
generating names that satisfy the above criteria. The basic idea is to name
all quantities by their types. This simple statement requires considerable
elaboration. (What is meant by "types"? What happens if "types" are not
unique?) However, once we can agree on the framework, the benefits readily
follow. The following are examples:

  1.  The names will be mnemonic in a very specific sense: if someone
      remembers the type of a quantity or how it is constructed from other
      types, the name will be readily apparent.
  2.  The names will be suggestive as well: we will be able to map any name
      into the type of the quantity, hence obtaining information about the
      shape and the use of the quantity.
  3.  The names will be consistent because they will have been produced by
      the same rules.
  4.  The decision on the name will be mechanical, thus speedy.
  5.  Expressions in the program can be subjected to consistency checks that
      are very similar to the "dimension" checks in physics.


Type Calculus

  As suggested above, the concept of "type" in this context is determined by
the set of operations that can be applied to a quantity.  The test for type
equivalence is simple: could the same set of operations be meaningfully
applied to the quantities in questions? If so, the types are thought to be
the same. If there are operations which apply to a quantity in exclusion of
others, the type of the quantity is different.

  The concept of "operation" is considered quite generally here; "being the
subscript of array A" or "being the second parameter of procedure Position"
are operations on quantity x (and "A" or "Position" as well). The point is
that "integers" x and y are not of the same type if Position (x,y) is legal
but Position (y,x) is nonsensical. Here we can also sense how the concepts of
type and name merge: x is so named because it is an x-coordinate, and it
seems that its type is also an x-coordinate. Most programmers probably would
have named such a quantity x. In this instance, the conventions merely codify
and clarify what has been widespread programming practice.

  Note that the above definition of type (which, incidentally, is suggested
by languages such as SIMULA and Smalltalk) is a superset of the more common
definition which takes only the quantity's representation into account.
Naturally, if the representations of x and y are different, there will exist
some operations that could be applied to x but not y, or vice versa.

  Let us not forget that we are talking about conventions which are to be
used by humans for the benefit of humans. Capabilities or restrictions of the
programming environment are not at issue here. The exact determination of
what constitutes a "type" is not critical, either. If a quantity is
incorrectly classified, we have style problem, not a bug.


Naming Rules

  My thesis discusses in detail the following specific naming rules:

  1.  Quantities are named by their type possibly followed by a qualifier. A
      convenient (and legal) punctuation is recommended to separate the type
      and qualifier part of a name. (In C, we use a capital initial for the
      qualifier as in rowFirst: row is the type; First is the qualifier.)
  2.  Qualifiers distinguish quantities that are of the same type and that
      exist within the same naming context. Note that contexts may include
      the whole system, a block, a procedure, or a data structure (for
      fields), depending on the programming environment. If one of the
      "standard qualifiers" is applicable, it should be used. Otherwise, the
      programmer can choose the qualifier. The choice should be simple to
      make, because the qualifier needs to be unique only within the type and
      within the scope - a set that is expected to be small in most cases. In
      rare instances more than one qualifier may appear in a name.  Standard
      qualifiers and their associated semantics are listed below.  An example
      is worthwhile: rowLast is a type row value; that is, the last element
      in an interval. The definition of "Last" states that the interval is
      "closed"; i.e., a loop through the interval should include rowLast as
      its last value.

  3.  Simple types are named by short tags that are chosen by the programmer.
      The recommendation that the tags be small is startling to many
      programmers.  The essential reason for short tags is to make the
      implementation of rule 4 realistic. Other reasons are listed below.

  4.  Names of constructed types should be constructed from the names of the
      constituent types. A number of standard schemes for constructing
      pointer, array, and different types exist. Other constructions may be
      defined as required. For example, the prefix p is used to construct
      pointers.  ProwLast (prowLast) is then the name of a particular pointer
      to a row type value that defines the end of a closed interval. The
      standard type constructions are also listed below.

  In principle, the conventions can be enriched by new type construction
schemes. However, the standard constructions proved to be sufficient in years
of use. It is worth noting that the types for data structures are generally
not constructed from the tags of their fields. First of all, constructions
with over two components would be unwieldy. More importantly, the invariant
property of data structure, the set of operations in which they participate,
seems to be largely independent of the fields of the structure that determine
only the representation. We all have had numerous experiences with changes in
data structures that left the operations (but not the implementation of the
operations) unchanged. Consequently, I recommend the use of a new tag for
every new data structure. The tag with some punctuation (upper case initial
or all upper case) should also be used as the structure name in the program.
New tags should also be used if the constructions accumulate to the point
where readability suffers.

  In my experience, tags are more difficult to choose than qualifiers. When a
new tag is needed, the first impulse is to use a short descriptive common
generic English term as the type name. This is almost always a mistake. One
should not preempt the most useful English phrases for the provincial
purposes of any given version of a given program. Chances are that the same
generic term could be equally applicable to many more types in the same
program. How will we know which is the one with the pretty "logical" name,
and which have the more arbitrary variants typically obtained by omitting
various vowels or by other disfigurement? Also, in communicating with the
programmer, how do we distinguish the generic use of the common term from the
reserved technical usage? By inflection? In the long run, an acronym that is
not an English worked may work out the best for tags. Related types may then
share some of the letters of the acronym. In speech, the acronym may be
spelled out, or a pronounceable nickname may be used. When hearing the
special names, the informed listener will know that the special technical
meaning should be understood. Generic terms should remain free for generic
usage.

  For example, a color graphics program may have a set of internal values
that denote colors. What should one call the manifest value for the color
red? The obvious choice (which is "wrong" here) is RED. The problem with RED
is that it does not identify its type. Is it a label or a procedure that
turns objects RED? Even if we know that it is a constant (because it is
spelled all caps, for example), there might be several color-related types.
Of which one is RED an instance? If I see a procedure defined as
paint(color), may I call it RED as an argument?  Has the word RED been used
for any other purpose within the program?  So we decide to find a tag for the
color type and use the word Red as a qualifier.

  Note that the obvious choice for the qualifier is in fact that the
"correct" one! This is because the use of qualifiers are not hampered by any
of the above difficulties. Qualifiers are not "exclusive" (or rather they are
exclusive only within a smaller set) so we essentially need not take into
account the possibility of other uses of the term "Red." The technical use of
the term will be clear to everyone when the qualifier is paired up with an
obviously technical type tag. Since qualifiers (usually) do not participate
in type construction, there is no inherent reason why they would need to be
especially short.

  Conversely, the tag for the type of the color value should not be "color."
Just consider all the other color related types that may appear in the
graphics program (or in a future variant): hardware encoding of color, color
map entry number, absolute pointer to color map entry, color values in
alternate color mapping mode, hue-brightness-saturation triples, other color
values in external interfaces; printers, plotters, interacting external
software, etc.  Furthermore, the tag will have to appear in names with
constructed types and qualifiers.

  A typical arbitrary choice could be "co" (pronounced see-oh). Or, if "co"
was already taken, "cv", "cl", "kl", and so on. Note that the mnemonic value
of the tags is just about average: not too bad, but not too good either. The
conventions cannot help with creating names that are inherently mnemonic,
instead they identify, compress, and contain those parts of the program that
are truly individual, thus arbitrary.  The lack of inherent meaning should be
compensated by ample comments whenever a new tag is introduced. This is a
reasonable suggestion since the number of basic tags remains very small even
in a large system.

  In conclusion, the name of our quantity would be "coRed", provided that the
color type "co" is properly documented. The value of the name will show later
in program segments such as the following:

      if co == coRed then *mpcopx[coRed]+=dx ...

  At a glance we can see that the variable co is compared with a quantity of
its own kind; coRed is also used as a subscript to an array whose domain is
of the correct type. Furthermore, as we will see, the color is mapped into a
pointer to "x", which is de-referenced (by the *operator in this example) to
yield an x type value, which is then incremented by a "delta x" type value.
Such "dimensional analysis" does not guarantee that the program is completely
free from bugs, but it does help to eliminate the most common kinds. It also
lends a certain rhythm to the writing of the code: "Let's see, I have a co in
hand and I need an x; do I have a mpcox? No, but there is a mpcopx that will
give me a px; *px will get me the x...", and so on.


Naming for "Writability"

  A good yardstick for choosing a name is to try to imagine that there is an
extraordinary reward for two programmers if they can independently come up
with the same program text for the same problem.  Both programmers know the
reward, but cannot otherwise communicate.  Such an experiment would be
futile, of course, for any sizable problem, but it is a neat goal. The reward
of real life is that a program written by someone else, which is identical to
what one's own program would have been, is extremely readable and modifiable.
By the proper use of the conventions, the idea can be approached very
closely, give or take a relatively few tags and possibly some qualifiers. The
leverage of the tags is enormous. If they are communicated, or are agreed on
beforehand, or come from a common source, the goal becomes reachable and the
reward may be reaped. This makes the documentation of the tags all the more
important.

  An example of such a consideration is the discretionary use of qualifiers
in small scopes where a quantity's type is likely to be unique, for example
in small procedures with a few parameters and locals or in data structures
which typically have only a few fields.  One might prefer to attach a
qualifier even to a quantity with a unique type of "writability", the ability
for someone else to come up with the name without hesitation. As many
textbooks point out, the "someone else" can be the same programmer sometime
in the future revisiting the long forgotten code. Conclusion: do not use
qualifiers when not needed, even if they seem valuable.