| [Home] | [News] | [API] | [Example usage] | [FAQ] | [Roadmap] | [Download] | [Contact] |
The naming convention used here follows a variation of the well-known Hungarian naming convention [#!Hungarian-naming!#].
The core idea is that classes, methods, and variables are prefixed by a short code that designates the component type and access, followed by an underscore and the name itself.
The usage of prefixing can lead to somewhat long prefix codes. This is an unfortunate consequence of Hungarian-based naming, and violates the so-called ninth commandment of the humorous but quite meaningful ``Ten Commandments for C Programmers'' - see here .
Names are descriptive and in lower case. Names comprised of multi-words are concatenated together, with the beginning of each new word capitalized - the overriding concern is that all the words must denote a single concept. This can result in cumbersome appearing names, but brevity is purposefully sacrificed for clarity in meaning. Consider also that what might appear clumsy in English can be quite natural in other languages. Most Germanic languages (including German, Dutch, Flemish, Afrikaans) regularly concatenate multiple words if together they describe a single concept, e.g. the Afrikaans driepoothouttafel - three legged wooden table and onderwateropsoringsapparaat - underwater detection apparatus.
All classes are prefixed by the letter c (or C) and may be additionally followed by an underscore. For example, c_SMessage (for a messaging class), CMatrix (a mathematical class implementing matrix functionality) or C_agent (an intelligent agent class).
Derived classes use the parent class name, suffixed with an underscore name. Thus, C_agent_Q is a sub-class of C_agent based on Q-learning, and similarly for C_agent_Q_cont_pendulum which is a continuous-time (cont) subclass of C_agent_Q. The pendulum designates this class as being derived from C_agent_Q_cont and tailored to pendulum systems. In this manner, the name of a class mirrors the effect of sub-classing: more specific classes are down the inheritance chain, just as the most specific parts of the class name are at the end of the name.
Class naming is really a subset of naming variables (since class instances are variables in their own right). Variables describe a single concept / state / information necessary for the functioning of the software system, and comprise two parts - a identifying type/access prefix, and a descriptive conceptual name. The name can be as long as is deemed necessary to convey unambiguous naming (as a matter of fact, somewhat long and cumbersome names are favored over short, non-descriptive names). Should a few ``words'' be required to convey meaning, they are concatenated together with the first letter of each new word capitalized to improve readability, such as negativeTerminalReward.
Additionally, variables are prefixed with a series of characters denoting their type and access - see Table 1.1 (note that some of the type characters are similar to standard C-type format strings for functions such as printf(1)). Note also that designating characters can be strung together where syntactically meaningful, such as lf_baseLine (a long float (or double) variable) or plf_baseLine (a pointer to a long float variable). In the case of C-type chars, pch (pointer to char) can indicate a C-type string array.
| Variable type | Designating character | Example |
| (C++) class | c|C|[< >]_ | CMatrix, c_SSocket |
| (C++) string | str_ | str_payload |
| (C++) bool | b_ | b_anotherIterationDo |
| long | l_ | lf_baseLine |
| float / double | f_ | f_deltaEpsilon |
| int / byte | [d_] | i, j, k, d_level |
| char | ch_ | ch_input |
| pointer | p | pch_message |
| function / method argument | a | af_num, apstr_output |
| User defined types | derived from type name | pM_QSpace |
The naming of methods (functions in C++ parlance) follows an analogous syntax. Note, though, that the method naming does not necessarily need to convey the arguments passed to it, or the values it returns, but focuses rather on the meaning of the method. Since methods are operations that dynamically act on static data, the underlying naming approach consists of two parts, an object_verb concatenation. All methods can be identified by this object and verb combination, strung together in a method reminiscent of Reverse Polish Notation. Examples include pendulumOverview_draw(), problemDomain_nextStateDetermine(). If a method has only a single name-part, it must be a verb, such as print(), initialise(), etc. Occasionally, it makes sense to prepend a method with a variable designating character to further specify its behavior, i.e. b_anotherIteration_shouldDo() is a method that returns a bool value and determines whether or not another iteration should be done.