[Avr-libc-corelib] Re: proposed corelib style guide

[Ruddick Lawrence]

Another category I just thought of that we should probably add:

INITIALIZATION
-If a module has any initialization code, it should go in a function with the module name prepended onto _init (ie, uart_init())

-Init functions should not enable global interrupts [pro: developer has more control, and interrupts will only happen after everything is set up; con: subsytems don't "go" as soon as they are set up]
-All registers that the initialization function modifies should follow the read/modify/write paradigm to avoid overwriting other parts of the register

[Do we want some way to tell if two init functions will conflict (ie, trying to use the same timer with both PWM and output compare)? I guess this goes back to determining the uses of each pin for each AVR model]

On Tue, Sep 22, 2009 at 5:23 PM, Ruddick Lawrence <address@hidden> wrote:

Hi all,

Based on the recent discussion, and some things that I find sensical, I have put together this proposed style guide. Please respond to the list with comments and additions. Certain stylistic decisions are just a matter of taste, so try to be aware of this when responding. Some decisions are to try to keep the code consistent with avr-libc code (speaking of which, is there already a style guide created for that?).

Some of the following style doesn't make sense yet, or may change once we have a more detailed definition of the structure, but I always find it's easier to edit than to create, so this gives a starting point. My commentary is in square brackets.

Ruddick

===============

MODULES
-Each module will have a short designation that is unique in corelib (ie, uart, timer, pwm)
-The public API for each module should be in a single header file named after the module (ie, uart.h) [is this too restrictive?]

FILES
-File names should be lower-cased with words separated by underscores.
-All files in a module should have the module name at the beginning of the filename (ie, uart.c, uart_calculations.h).
-All files should have a standard header [which will be defined, probably with the BSD, contributors, etc]

COMMENTS
-Comments should conform to the Doxygen style [I think there's one already for avr-libc]
-All functions should have a description of the arguments they take and the values they return

FUNCTIONS
-Function names should be lower-cased with words separated by underscores.
-All public functions in a module should have the module name at the beginning of the filename (ie, uart_init(), spi_send()).
-Private functions should be declared as static.
[Do we want to prepend private functions with an underscore (ie, _my_private_function())?]

VARIABLES
-Variable names should be lower-cased with words separated by underscores.
-Private variables should be declared as static.
-No global variables [this was always hammered into me. Is it actually a good policy?]
[Do we want to prepend private variables with an underscore (ie, _my_private_var)?]

CONSTANTS
-Constant names should be all upper-cased with words separated by underscores (ie, CONSTANT_DEFINITION)
-Constant names should have the module name at the beginning (ie, UART_BAUD) [Do we actually want this?]
[Do we want to specify when to use #define's and when to use enums? How about const?]

DATA STRUCTURES
-Data typedefs should be in camel case, with the first letter capitalized (ie, CamelCase) [This is pretty subjective, but I feel it distinguishes between a data type and an instance]
-Data typedefs should end in _t (ie, LongTimer_t)
-Any member variables should follow the rules specified above, under VARIABLES.