Standards for Commenting an Embedded Code

[scorrpeio]

Hello,

Is there any standard of what should be included in commenting the Embedded Code?

Right now, I am of my own, using following information in commenting...


For .c file

/************************************************************************************************
 * File Name: - UART.c
 * COPYRIGHT NOTICE: (C) 2011 <Company Name>
 * All Rights reserved
************************************************************************************************/
/*****************************************************************************************
 * File Name:    - UART.c
 * Date Created: - 25.July.2011
 * Created By:   - 
 *
 * Dependencies: - The RxBuf of MCU is mapped with the char buffer which is declared 
 *                 global in other .c file
 *                 While porting this file in other projects, care should be taken that
 *                 RxBuf of MCU should be mapped as per project requirement.
 *    
 * Description:  - 1. This file implements the driver for UART communication.
 *                 2. It has routines for Initialisation of UART, sending single byte on
 *                    UART port by polling and receiving single byte through interrupt.    
 *
 * Compiler Used: - CCS4.0
 * MCU used:      - MSP430F5418A
 * Date Modified: -
 * Modifications: -
 * Modified By:   -
*****************************************************************************************/
/////////////////////////////////////////////////////////////////////////////////////////
// INCLUDE FILES
/////////////////////////////////////////////////////////////////////////////////////////
#include "Config.h"
#include "StdTypes.h"

#include "Display.h"
#include "Slave.h"
#include "UART.h"

/////////////////////////////////////////////////////////////////////////////////////////
// GLOBAL VARIABLES
/////////////////////////////////////////////////////////////////////////////////////////

/* The following buffer is used to store data received.*/  
UINT8_T u8Buf[];
	
/////////////////////////////////////////////////////////////////////////////////////////
// FUNCTION DEFINITIONS
/////////////////////////////////////////////////////////////////////////////////////////
/****************************************************************************************
 * Function Name- UART_CallFunc
 * Return Type- void
 * Argument List- UINT8_T u8FunctionNo
 * Calling Functions- 
 * Called Functions-  
 *   
 * Global Variables Affected- none
 *
 * Description- 
 * Note - 
****************************************************************************************/	
...

//.c file ends here

for.h file

/************************************************************************************************
 * File Name: - UART.h
 * COPYRIGHT NOTICE: (C) 2011 <Company Name>
 * All Rights reserved
************************************************************************************************/

/*****************************************************************************************
 * File Name:    - UART.h
 * Date Created: - 25.July.2011
 * Created By:   - 
 *
 * Dependencies: -
 * Description:  - This header file contains the declarations of the functions used in
 *                 UART.c File. Further the extern variables are declared here. 
 *                 The macros associated with function call also go here.
 *
 * Compiler Used: - CCS4.0
 * MCU used:      - MSP430F5418A
 * Date Modified: -
 * Modifications: -
 * Modified By:   -
*****************************************************************************************/
#ifndef UART_H_
#define UART_H_

/////////////////////////////////////////////////////////////////////////////////////////
// MACRO DEFINITIONS
/////////////////////////////////////////////////////////////////////////////////////////
/* Macros associated with Calling of Function in UART_Driver.c file */

/////////////////////////////////////////////////////////////////////////////////////////
// EXTERN VARIABLES
/////////////////////////////////////////////////////////////////////////////////////////
/* Variables Declared global in file x.c  */
...

/* Variables Declared global in file y.c  */
...

/////////////////////////////////////////////////////////////////////////////////////////
// FUNCTION DECLARATION
/////////////////////////////////////////////////////////////////////////////////////////
...

#endif /*UART_H_*/

- - - Updated - - -

Please let me know, if something more should be added in it.

 

[Tahmid]

I don't know of any standards. You should use whichever standard/format is best for you. Your commenting should be such that you (and any other co-programmers/designers) can easily understand the code whenever the code is viewed or inspected, at any later time.

 

[alexan_e]

You may find this useful www.grantronics.com.au/files/CStyleGuide.pdf

Section 2.3 and section 4

 

[nsaspook]

An important thing that is missing on some detailed comments is 'What and Why' we need to do this not just 'How' it's doing it.

**broken link removed**

 

[scorrpeio]

ok... I will read these books first now and if have any doubt, will revert back