AVR Core Library

Style Guidelines

When developing code for AVR Core Library, please follow the following guidelines so the code has a uniform look and to help other developers understand your code.

Naming Conventions

We will refer to the following types of naming:

CamelCase: Has a captial letter for each word, including the first, and no underscores.
lower_case: Has all lower case letters, with words separated by underscores.
UPPER_CASE: Has all upper case letters, with words separated by underscores.

Modules

Each module has a short designation that is unique in corelib (ie, uart, timer, pwm)

Files

Files use lower_case.

Filenames start with the designator of the module that the file belongs to (ie, uart.c, uart_calculations.h).

Functions

Function names and arguments use lower_case.

Public functions have the module name at the beginning of the filename (ie, uart_init(), spi_send()).

A module's initialization function is named module_init() (ie, uart_init()).

Variables

Variable names use lower_case.

Never use global variables, but if you do, prepend the name with g_.

Constants

Constant names use UPPER_CASE.

Constant names should have the module name at the beginning (ie, UART_BAUD).

Data Structures

Data typedefs use lower_case and end in _t (ie, long_timer_t).

Any member variables follow the guidelines for variables specified above.

Formatting

As a general guideline, code uses the BSD Allman formatting.

Indent each block by 4 spaces. Do not use the tab character.

Both opening and closing braces go on their own line.

Use braces for all statements that could have them, even for enclosing a single line.

Interrupts

The avr-corelib gives the client code as much control over interrupts as possible, so modules do not define interrupt service routine vectors or enable/disable global interrupts.

Put interrupt service routines into inline static functions (one for each vector) that the client code can put into the appropriate vector. Clearly state in the documentation any functions that have to go into a vector.

Make it clear in the documentation when global interrupts should be enabled, but leave it to the client code.

Constant Values

Public constants (in header files) use #define's for single values because it will not reserve memory space.

Private constants use static const values to limit the scope to the module.

Registers

Whenever possible, use the read/modify/write paradigm to change registers in order to avoid overwriting other parts of the register.

Scope

Although C has no "private" definition, any functions and otherwise global variables not meant to be used by client code should be declared static.

API

Each module's API is defined in a single header file, named after the module (ie, uart.h).

Documentation

It is essential for code in a collaborative project to be well-documented. The avr-corelib uses Doxygen to generate documentation from certain comments. Comment all code using the Doxygen syntax.

Make sure to document all public files, variables, and functions, including arguments and return values. Each module's documentation clearly states all interrupt functions that client code needs to include in interrupt vectors, whether global interrupts need to be enabled, and what happens to the module's functionality if global interrupts are disabled.

Each module also has a usage guideline and a comprehensible example of use.

Errors and Warnings

Still unclear exactly the best way to consistently report errors across the modules. Will probably be hashed out once a module or two are more developed. Possibilities include compile-time check of pin/functionality usage in each module, and defining what happens if the module is re-initialized.

License

All code in the AVR Core Library must use the BSD license. All files must have the following license and copyright statement at the beginning of the file:

Copyright (c) <YEAR>, <OWNER>
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

    * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
    * Neither the name of the  nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.