Continue to Site

Welcome to EDAboard.com

Welcome to our site! EDAboard.com is an international Electronics Discussion Forum focused on EDA software, circuits, schematics, books, theory, papers, asic, pld, 8051, DSP, Network, RF, Analog Design, PCB, Service Manuals... and a whole lot more! To participate you need to register. Registration is free. Click here to register now.

Standards for Commenting an Embedded Code

Status
Not open for further replies.

scorrpeio

Full Member level 5
Joined
Dec 26, 2006
Messages
286
Helped
10
Reputation
20
Reaction score
9
Trophy points
1,298
Activity points
3,496
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
Code:
/************************************************************************************************
 * 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
Code:
/************************************************************************************************
 * 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.
 

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.
 

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**
 
ok... I will read these books first now and if have any doubt, will revert back
 

Status
Not open for further replies.

Part and Inventory Search

Welcome to EDABoard.com

Sponsor

Back
Top