Component Coding Conventions

To make it easier to read and maintain the code, the component library has unified coding conventions, and uses Doxygen to generate the documents.

Below are what you need to pay attention to. For details, please refer to our code.

1. Type definitions

• 1.1 The program needs to be indented with 4 spaces.

• 1.2 Use spaces instead of TAB to align the code. Note: In different editors, a tab is defined as different numbers of spaces, which will lead to code disalignment. Using spaces can avoid this issue.

• 1.3 Blank lines must be used to separate independent program blocks and follow variable declarations.

• 1.4 Statements with over 80 characters should be written in multiple lines; long expressions need to start a new line at the low-priority command characters, and the command characters should be the beginning of the new line with suitable indentation to keep the program neat.

• 1.5 Statements like if, for, do, while, case, switch, default, etc. should occupy a line, and be surrounded by {} no matter how long the statement is.

• 1.6 In a program, the beginning of a function, the declaration of a structure, and a loop should be indented, and the processing statements in a case command should be indented too.

• 1.7 The delimiter in a program like { and } should occupy one line, locate in the same column, and be left-aligned with relative statements. In a program, the beginning of function body, the definition of class and enumeration, and statements like if, for, do, while, switch, case need to be indented as mentioned above.

• 1.8 Spaces need to be added before or (and) after the instruction character when there are more than 2 keywords or variables or constants in the equivalent operation. Closely related instruction characters (e.g. ->) should have no spaces in between when there is no equivalent operations.

2. Comments

2.1. File header

The file header should list the brief introduction, author, date and license of the file, like this:

//*****************************************************************************
//
//! \file xadc.h
//! \brief Defines and Macros for ADC API.
//! \version V2.0.0
//! \date 9/30/2011
//! \author CooCox
//! \copy
//!
//! Copyright (c)  2011, CooCox 
//! All rights reserved.
//! 
//! Redistribution and use in source and binary forms, with or without 
//! modification, are permitted provided that the following conditions 
//! are met: 
//! 
//!     * Redistributions of source code must retain the above copyright 
//! notice, this list of conditions and the following disclaimer. 
//!     * Redistributions in binary form must reproduce the above copyright
//! notice, this list of conditions and the following disclaimer in the
//! documentation and/or other materials provided with the distribution. 
//!     * Neither the name of the  nor the names of its 
//! contributors may be used to endorse or promote products derived 
//! from this software without specific prior written permission. 
//! 
//! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
//! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
//! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
//! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE 
//! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
//! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
//! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
//! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
//! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
//! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 
//! THE POSSIBILITY OF SUCH DAMAGE.
//
//*****************************************************************************

Words start with \ are Doxygen commands, like file, \brief, and \date.

2.2. Function header

//*****************************************************************************
//
//! \brief Configures an ADC digital comparator.
//!
//! \param ulBase is the base address of the ADC module.
//! \param ulCompID is the ID of the comparator to configure.
//! \param ulConfig is the configuration of the comparator.
//!
//! This function will configure a comparator.  The \e ulConfig parameter is
//! the result of xADC_COMP_INT_xxx value. Reference 
//! \ref xADC_Comparator_Int_Condition.
//!
//! \note Here are some matters needing attention.
//!
//! \return None.
//
//*****************************************************************************

The sequence should be like this: \brief, \param(optional), details(optional), \note(optional), and \return.

2.3. Function comments

{
...    

    //
    // Get the ADC_CMPRx register address
    //
    ulCompRegAddr = ulBase + ADC_CMPR0 + (4 * ulCompID);

...    
}

2.4. Macro definition comments

//
//! Compare condition is greater or equal
//
#define ADC_COMP_GREATER_EQUAL  0x00000004

2.5. Doxygen group

//*****************************************************************************
//
//! \addtogroup NUC1xx_ADC_Operation_Mode NUC1xx ADC Operation Mode
//! \brief ADC A/D Converter Operation Mode.
//! @{
//
//*****************************************************************************

...

//*****************************************************************************
//
//! @}
//
//*****************************************************************************

3. Identifiers naming

• 3.1 Variables are generally named as this: Type prefix + Noun with the first letter capitalized, e.g. egisterValue, pucBuffer.

• 3.2. typedef definitions are generally named as: t + Noun with the first letter capitalized, e.g. tBoolean.

• 3.3. Functions are generally named as: Module + Verb with the first letter capitalized, e.g. SysCtlClockSet, GPIOPinsRead.

• 3.4. Marco definitions are generally named as: Module + capitalized Noun separated with _, e.g. xADC_EVENT_END_CONVERSION.

Coding notices

• Try not to use the similar variable names such as ulTmp, ulTmp1.
• All the variables need to be initialized.
• To modify some bits of a register, you need to follow the standard process of "Reading - Modifying - Writing".

     Note: Use bit-band if you can.
  

• In functions, all return statements should be followed with parentheses, e.g. return (0);
• All variables should use uinx_t type. Original data types like int are not recommended.
• Tab is not allowed in code. Use spaces for indentation.
• Extra spaces are NOT allowed at the end of the code.
• All if, switch, and while statements, regardless of the length of the statements, must be followed with braces ({})
• Use a space after #end, followed by comments of corresponding #if statement.
• Generally a code line has about 80 characters, which can be increased to 120 characters according to actual situations.
• All type conversions need to be declared explicitly.
• All Macro variables are in capital letters.
• Use a space after #define, and then define the Macro's name, and write the definition in column 33. In special situation, you can write the definitions in other column, but you need to make all the Macro code in the same file start from the same column.
• Peripherals are named as: Peripheral name + ID, e.g. DMA1, DMA2.
• Registers are named as: Peripheral name+ _ + Register name, e.g. DMA_CCR1. The register name should be in accordance with the Reference Manual.
• Peripheral APIs are named as: Peripheral name + _ + API function, e.g. DMA_Enable, DMA_Disable.
• To classify the peripheral APIs, the APIs should be written according to the orthogonal principle, to reduce the coupling of different APIs.

       e.g. DMA_IntEnable function should has 2 interface parameters (the peripheral base address and the interrupt flag).               
       Negative example: Functions over-coupled
                extern void I2CDMAEnable(unsigned long ulBase, unsigned long ulDMALast);  
  

• goto statement can only be used in error handling section of the code
• Bugs caused by priority errors: e.g. == has higher priority than &, so you need to add braces in the expression below:

       while(xHWREG(DMA1_BASE + DMA_ISR) & DMA_ISR_TCIF7 == 0); 
       should be modified into
       while((xHWREG(DMA1_BASE + DMA_ISR) & DMA_ISR_TCIF7) == 0);