3.2. Naming Conventions

The MCAF uses the following naming conventions:

• A prefix is used for all functions and types, so that these functions are less likely to conflict with user-defined code. The major prefixes are

  • MC_ — Motor Control Library
  • MCAF_ — Motor Control Application Framework
  • HAL_ — Hardware Abstraction Layer
  • BSP_ — Board Support Package
  • MCAPI_ — Motion Control API

• Functions use a prefix and UpperCamelCase, i.e. one or more words with each word capitalized including the first one. These generally fall into one of two types:

  • Actions: <noun-phrase> <action>

    MCAF_CoastdownTimerReset()
    MCAF_PllEstimatorInit()
    

  • Getters: <noun-phrase> <adjective-phrase> or <noun-phrase> <property>

    MCAF_OperatingModeNormal()
    MCAF_StartupHasCompleted()
    

• Types are defined in all capital letters with underscores between words:

  typedef struct
  {
      int16_t d;
      int16_t q;
  } MC_DQ_T;
  

• Enum constants are defined in all capital letters with underscores between words. Enum constants in the same type should have a common prefix that is specific to that type, for instance the MADC_ prefix in this example:

  typedef enum tagMCAF_ADC_SELECT
  {
      MADC_VDC           = 0,
      MADC_POTENTIOMETER = 1
  } MCAF_ADC_SELECT;
  

• Variables and struct/union members are declared in lowerCamelCase, i.e. one or more words with each word capitalized except the first one:

  int16_t           thetaElectrical;
  int16_t           omegaElectrical;
  MC_SINCOS_T       sincos;
  MCAF_MOTOR_DATA *pmotor;
  uint16_t          subsampleCounter;
  

  • Underscore characters in variable names and structure members are discouraged.
  • Prefixes are not used in global variables, because the number of global variables is minimal. In addition, their names may be changed by customers without impact to the MCAF, since the framework’s modules do not access them directly.

• The MCAF uses the standard C types defined in <stdint.h> and <stdbool.h>, such as int16_t, uint16_t, int32_t, and bool, to denote integers of specific bit widths. Earlier application note code included lines such as the following:

  // use of implementation-dependent types
  int count = 0;
  short qVqRef;
  unsigned long Startup_Ramp = 0;
  
  // attempt to define specific type aliases
  typedef unsigned short WORD;
  typedef signed int SFRAC16;
  typedef unsigned char  BYTE;
  typedef unsigned char  bool;
  #define False  0
  #define True   1
  

  These have since been converted to use <stdint.h> and <stdbool.h>.

3.2.1. Additional Naming Guidelines

• The MCAF sometimes uses variable names which are symbolic in nature (for example theta or omega or iq) because these have specific meanings in motor control theory.
• The camelCase convention in symbolic names should not change the capitalization of subscripts, for example we use idq and ialphabeta rather than iDQ or iAlphaBeta.
• In general, variable names should start off with a general description of the quantity they represent and should be followed by more specific qualifiers. This allows related sibling variables or structure members to be alphabetically adjacent, and allows readers to narrow down the topic of interest as they read from left to right. Thus iMaximum, iMinimum, vMaximum, vMinimum is better than maximumCurrent, minimumCurrent, minimumVoltage, maximumVoltage.