At DMMD we try to follow a “make sense” approach to our programming style. Whenever possible we use UML notation to describe the class interaction. To drive home certain concepts we steer clear of any one particular style of notation and provide the notation that we believe makes the explanation most intuitive. For example, we will use colors to associate properties of certain objects. In our projects, we try to conform to the following programming style:
- All member variables and objects (but not functions) are prefixed with an “m_”. For
example: “m_iMyIntegerMemberVariable” or “m_MyObjectMember”.
- As much as possible, all variables use the Hungarian notation. Each variable is prefixed
with the type or functionality shortcut for that variable: iMyIntegerVariable,
fMyFloatVariable, bMyBooleanVariable, pMyPointer, etc.
- Based on the project or library name, classes are prefixed with three or two lower cases. For example: dmaMyClass for a class that’s part of our DMA image processing library.
- We use name spaces that are unique for different projects, and especially libraries.
- For variables and function names we use the camel-back notation. Variables always
start with lower case and functions with upper case: MyFunctionName and myVariableName.
- We always use full names and unless we are referencing well established acronyms, the full word is spelled out. For example: “ShiftImageLeft()” as opposed to “SftImgLft()”. The goal is to make the code as readable as possible by simply reading the variable names.
- For source code documentation we use Doxygen. For the design document we use a multitude of graphical and technical writing applications that allow us to capture the concepts of our designs at a level similar to a white paper or even at the level of a technical journal paper.
At DMMD we believe that properly naming variables and functions is one of the most important task a programmer can take to make the code more readable and understandable. Giving names that provide the most information about the responsibilities of a function or variable is critical. Renaming variables to have the most meaningful name is a common routine in the development of any of DMMD’s code.
When coming up with variable, function or class names we keep in mind the following:
Higher frequency is inversely proportional with the amount of information. This means the more often an event happens, the less information there is when that event happens. As an example, the sun rises and sets daily. Stating this fact will not provide any additional information to a user. However, if one would state that one day the sun did not rise, all of a sudden there would have a lot of information that something terribly wrong happened.
In this same fashion using names that are frequently used throughout the code is usually not a good naming strategy. For example, each class could begin with the name “class”, but because this would happen for every class in the library and any class in any library anywhere in the world, the name “class” does not carry a lot of information and so it can be dropped from the name of any particular class.
More details on naming strategies are given in my next blog.
– Darian Muresan