Guideline Object Format for C based objects (Suggestions? Ideas?)

TJHJ

Every book I look in has a different way of doing the layout, but here is a general summary. If you all would make suggestions or changes maybe we could all use it for consistency as C seems to have no hard defined format. Ill change this main post for use as a reference.

Ok so each object should have two files minimum. A header file and a function file




Ideas suggestions?

EDIT : Original code removed. See Below for a good layout.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
I owe everyone here a bunch, So thanks again for answering my dumb questions.
Projects. RG500 ECU system. PropCopter. Prop CanSat. Prop Paste Gun.
Suzuki RG500 in a RGV 250 frame.
Bimota V-Due (Running on the fuel injection system)
Aprilia RS250

Post Edited (TJHJ) : 4/9/2009 2:31:59 PM GMT

jazzed

Good start TJ. Some things to consider ...

Just one symantics note: We don't really talks about objects with "Standard C" although you do have classes and objects in C++. Normally they are just called modules or libraries. A module generally is one .c file and it's .h file. What you have described is a module. A library is many modules and often compiled into .a or .so binaries that have .h files to describe the API or Applications Program Interface (and have version numbers in linux for example but that's over-kill for our situation).

I don't really like pushing coding standards because it can be a PITA. I would call anything discussed in such terms a "guideline" for those who may not be familiar with the way things are done in some industry settings.

I'll borrow your starting point and expand on it.

/**
 * @file <filename.h> ... summary purpose of the module header file.
 * Optional details ...
 * Copyright (c) year, <copyright claimant name> 
 * See MIT license below for terms.
 */

#ifndef __OBJECT_FILE_LAYOUT_H__
#define __OBJECT_FILE_LAYOUT_H__

// in no certain order from here ...

/*
//INCLUDE FILES HERE
 * One should normally include files in .c files only.  Liberally including files in a .h file
 * will cause trouble and should be avoided unless there is a good reason.
 */

/*
// DEFINE MACROS
 * Prepend macros with your module name or abbreviation unless the module is a "common" file.
 * Many people enclose defines like this:
 * #ifndef MYDEFINE
 * #define MYDEFINE
 * #endif
 */

/*
//TYPE DEFINITIONS??? Here?
 * Typedefs for data structures or unique uncommon data types
 */

/*
//FUNCTION PROTOTYPES / DECLARATIONS
 * Always
 */

/*
//Possible labeling convention
//Name :
//Input :
//Output :
//Dependencies :
//Description : 

It is a good idea to do this somewhere ... I prefer the .h but others prefer keeping it
with the function implementation.  If folks use doxygen markup tags, the doxygen tool
will pick up the documentation regardless of where it lives.

Doxygen is embraced by professionals. It is a good tool and makes nice web page
or word compatible rtf documentation.

Basic Doxygen markups are as follows (optional):

"/**" ... this says begin a Doxygen block comment
"///" ... this says begin a Doxygen single line comment
@file <filename> ... tell Doxygen the filename contains markups and include
  in the doc set (use once in a file).
@note ... start a note
@param <name> <description> ... this defines a function parameter
@param out <name> <description> ... this defines a function parameter that will
  contain a modified value
@returns <description> ... for non void functions describes what the return value is

A simple doxygen function example is next.
 */

/**
 * get a pointer to the video buffer ...
 * Doxygen will automatically put the function name in the doc set for you.
 * @returns buffer pointer
 */
short* display_getBuffer(void);


#endif
//__OBJECT_FILE_LAYOUT_H__ ... never put a comment on the same line as #endif

/*
 MIT license statement
 */

/**
 * @file <filename.c> ... summary purpose of the module.
 * Optional details ...
 * Copyright (c) year, <copyright claimant name> 
 * See MIT license below for terms.
 */

/*
 * Include files
 */
#include <propeller.h>


/*
 * Global variables
 * Constants should be in header files only.
 * Globals should always be marked static ... or private if possible.
 */
static int gCog;

/*
 * Private function declarations ... optional. use if not in header file ...
 * eleminates positional function dependencies.
 */
static char* gettoken(char* str, char* tokenptr)

/*
 * Private functions implementation ... should match optional declaration in header.
 */

/*
 * get the next token from str and return in tokenptr ... simple way :)
 */
static char* gettoken(char* str, char* tokenptr)
{
  // parse token code to tokenptr TBD
  return tokenptr;
}


/*
 * Public functions implementation ...
 * should always have function declaration in header for API.
 */


/*
 * Start device by initializing PASM in a cog
 */
int devicename_start(void)
{
  // start pasm in cog and return cog+1
  gCog = cognew(....) + 1;
  return gCog;
}


/*
 MIT license statement
 */

That's the way I do it and I'm not asking any experienced programmers to follow it. This is a matter of style.
Everyone develops a style. I roll my eyes when someone suggests I have to do something a certain way ....
if I'm getting paid to follow a coding standard I'll follow it ... hesitantly [noparse]:)[/noparse]

Hope this helps.

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
--Steve


Propalyzer: Propeller PC Logic Analyzer
http://forums.parallax.com/showthread.php?p=788230

TJHJ

Thanks Jazzed,
I think that sums up my idea quite well.
And well I say object because well there in the object exchange....
You are right in saying standard is a bad idea, guideline is much better. I just wanted to get something I personally could follow that made sense to everyone else. And maybe if it would help someone else not make the same mistakes I have.

Maybe other people could post their style outline as a reference if needed.

TJ

▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
I owe everyone here a bunch, So thanks again for answering my dumb questions.
Projects. RG500 ECU system. PropCopter. Prop CanSat. Prop Paste Gun.
Suzuki RG500 in a RGV 250 frame.
Bimota V-Due (Running on the fuel injection system)
Aprilia RS250