Coding guidelines

From Gluonpilot

Documentation

Code documentation will be done with Doxygen according to the Qt rules. Take a look at the examples and libraries for documentation examples. The .h files will document the calling convention and what it should do.

/*!
 *    Writes a page to the flash chip
 *    @param page   The page address
 *    @param size   Number of bytes to read into buffer
 *    @param buffer Pointer to a buffer of at least "size" bytes. 
 */
void dataflash_write(int page, int size, unsigned char *buffer);

The .c file should contain the implementation, so the documentation should tell how something is achieved.

/*!
 *   This operation will write buffer of maximum 528 bytes to the dataflash.
 *   Basically, I'm just following the datasheet:
 *      - Command 0x84 allows us to write to buffer 1
 *      - Command 0x83 command the chip to write buffer 1 to the flash memory
 *
 *   Some simple simulations showed that it takes 0.7ms to write a page.
 */
void dataflash_write(int page, int size, unsigned char *buffer)

Code

Please write your code with care. If it's not understandable, nobody will use it. Some guidelines:

• Don't write methods much longer than a screen long.
• Don't copy code. Put it in a separate method!
• Use short documentation for everything that isn't obvious.
• When writing some more complex code, document it well in the code or on this wiki!
• Make sure all your libraries are documented with a simple example.
• Don't put hardware-dependent code where it shouldn't be. Use/Write a library for it!
• When writing interrupt routines, document how much of the stack it uses.

Some purist stuff:

• Tabs are 4 spaces wide
• Use tabs instead of spaces

Make sure your function declarations look like this:

void dataflash_write(int page, int size, unsigned char *buffer)
{
	int add1;

Libraries

All methods described in the header file show begin with the library's name followed by an underscore. e.g.: scp1000_open(), dataflash_write()

Including libraries will be done relative to the library path. So:

#include "microcontroller/microcontroller.h"