[Tinyos-host-mote-wg] [Tinyos-2.0wg] coding conventions revision
David Gay
dgay42 at gmail.com
Wed Aug 3 10:47:25 PDT 2005
- changed the package prefix rules
- the component suffixes are C for public and P for private (hmm -
better suggestions out there ?)
- acronyms should follow the Java style (Adc, not ADC, Hal not HAL,
etc), except for 2-letter acronyms (AM not Am)
We'll be fixing the files in pre2 to match tep3...
David
-------------- next part --------------
================================
Coding Standard
================================
:TEP: 3
:Group: TinyOS 2.0 Working Group
:Type: Best Current Practice
:Status: Draft
:TinyOS-Version: 2.x
:Author: Ion Yannopoulos
:Draft-Created: 31-Dec-2004
:Draft-Version: $Revision: 1.11 $
:Draft-Modified: $Date: 2005/08/03 17:45:13 $
:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
.. Note::
This document specifies a Best Current Practices for the
TinyOS Community, and requests discussion and suggestions for
improvements. Distribution of this memo is unlimited. This memo
is in full compliance with [TEP_1]_.
.. contents::
.. sectnum::
Introduction
========================================================================
The purpose of a naming convention is twofold:
- To avoid collisions which prevent compilation or lead to errors.
In TinyOS the most important place to avoid such collisions is in
interface and component names.
- To enable readers of the code to identify which names are grouped
together and which packages they are defined in.
Remember that code that is useful will end up being read far more often
than it is written. If you deviate from the suggestions or requirements
below, be consistent in how you do so. If you add any new conventions to
your code, note it in a README.
General Conventions
========================================================================
General
-------
- Avoid the use of acronyms and abbreviations that are not well known.
Try not to abbreviate "just because".
- Acronyms should be capitalized (as in Java), i.e., Adc, not ADC.
Exception: 2-letter acronyms should be all caps (e.g., AM for active
messages, not Am)
- If you need to abbreviate a word, do so consistently. Try to be
consistent with code outside your own.
- All code should be documented using `nesdoc` [nesdoc]_, `Doxygen`
[Doxygen]_ or `Javadoc` [Javadoc]_. Ideally each command, event and
function has documentation. At a bare minimum the interface, component,
class or file needs a paragraph of description.
- If you write code for a file, add an `@author` tag to the toplevel
documentation block.
Packages
========================================================================
For the purposes of this document a package is a collection of related
source and other files, in whatever languages are needed. A package is
a logical grouping. It may or may not correspond to a physical grouping
such as a single directory. In TinyOS a package is most often a
directory with zero or more subdirectories.
nesC and C do not currently provide any package support, thus names
of types and components in different packages might accidentally
clash. To make this less likely, judiciously use prefixes on groups
of related files (often, but not always, part of a single package).
See the examples below.
In a package, we distinguish between public components (intended to
be used and wired outside the package) and private components (only
used and wired within the package). This distinction is not enforced
by nesC.
Directory structure
-------------------
- Each package should have it's own directory. It may have as many
subdirectories as are necessary.
- The package's directory should match the package's prefix (if it
uses one), but in lower-case.
- The default packages in a TinyOS distribution are:
- `tos/system/`. Core TinyOS components. This directory's
components are the ones necessary for TinyOS to actually run.
- `tos/interfaces/`. Core TinyOS interfaces, including
hardware-independent abstractions. Expected to be heavily
used not just by `tos/system` but throughout all other code.
`tos/interfaces' should only contain interfaces named in TEPs.
- `tos/platforms/`. Contains code specific to mote platforms, but
chip-independent.
- `tos/chips/`. Contains code specific to particular chips and to
chips on particular platforms.
- `tos/libs/`. Contains interfaces and components which extend the
usefulness of TinyOS but which are not viewed as essential to its
operation. Libraries will likely contain subdirectories.
- `apps/`, `apps/demos`, `apps/tests`, `apps/tutorials`. Contain
applications with some division by purpose. Applications may
contain subdirectories.
- It is not necessary that packages other than the core break up their
components and their interfaces. The core should allow overrides of
components fairly easily however.
- Each directory should have a README describing its purpose.
Language Conventions
========================================================================
nesC convention
---------------
Names
.....
- All nesC files must have a `.nc` extension. The nesC compiler requires
that the filename match the interface or component name.
- Directory names should be lowercase.
- Interface and component names should be mixed case, starting upper
case.
- All public components should be suffixed with 'C'.
- All private components should be suffixed with 'P'.
- Avoid interfaces ending in 'C' or 'P'.
- If an interface and component are related it is useful if they have
the same name except for the suffix of the component.
- Commands, events, tasks and functions should be mixed case, starting
lower case.
- Events which handle the second half of a split-phase operation begun
in a command should have names that are related to the commands.
Making the command past tense or appending `'Done'` are suggested.
- Constants should be all upper case, words separated by underscores.
- Use of `#define` for integer constants is discouraged: use `enum`.
- Type arguments to generic components and interfaces should use the
same case as C types: all lower-case separated by underscores, ending
in '_t'.
- Module (global) variables should be mixed case, starting lower case.
Packages
........
- Each package may use a prefix for its component, interface and
global C names. These prefixes may sometimes be common to multiple
packages. Examples:
- All hardware presentation layer names start with Hpl (this is
an example of a shared prefix).
- Chip-specific hardware abstraction layer components and interfaces
start with the chip name, e.g., Atm128 for ATmega128.
- The Maté virtual machine uses the Mate to prefix all its names.
- Core TinyOS names (e.g., the timer components, the Init interface)
do not use a prefix.
- Some packages may use multiple prefixes. For instance, the ATmega128
chip package uses an Hpl prefix for hardware presentation layer
components and Atm128 for hardware abstraction layer components.
Preprocessor
............
- Don't use the nesC `includes` statement. It does not handle macro
inclusion properly. Use `#include` instead.
- Macros declared in an `.nc` file must be `#define`'d after the
`module` or `configuration` keyword to actually limit their scope to
the module.
- Macros which are meant for use in multiple `.nc` files should be
`#define`'d in a `#include`'d C header file.
- Use of macros should be minimized:
`#define` should only be used where `enum` and `inline` do not suffice.
- Arguments to `unique()` should be `#define` string constants rather
than strings. This minimizes nasty bugs from typos the compiler
can't catch.
C Convention
------------
- All C files have a .h (header) or (rarely) a .c (source) extension.
- Filenames associated with a component should have the same name as
the component.
- Filenames of a package should have a name with the package
prefix (if any).
- Filenames which are not associated with a component should be lowercase.
- C does not protect names in any way. If a package uses a prefix, it
should also use it for all types, tags, functions, variables,
constants and macros. This leads naturally to:
- Minimize C code outside of nesC files. In particular: most uses of
hardware specific macros in TinyOS 1.x should be replaced with nesC
components in TinyOS 2.x.
- C type names (define with `typedef`) should be lower case, words
separated by underscores and ending in `'_t'`.
- C tag names (for `struct`, `union`, or `enum`) should be lower case,
words separated by underscores. Types with tag names should provide
a typedef.
- C types which represent opaque pointers (for use in parameters) should
be named similar to other types but should end in `'_ptr_t'`.
- Functions should be lower case, words separated by underscores.
- Function macros (`#define` ) should be all upper case, words separated
by underscores.
- Using function macros is discouraged: use `inline` functions.
- Constants should be all upper case, words separated by underscores.
- Use of `#define` for integer constants is discouraged: use `enum`.
- Global variables should be mixed case, starting lower case.
Java convention
---------------
- The standard Java coding convention [Java_Coding_Convention]_
should be followed.
- All core TinyOS code is in the package `net.tinyos`.
Other languages
---------------
- No established conventions.
Author's Address
========================================================================
| Ion Yannopoulos
| 410 Soda Hall
| UC Berkeley
| Berkeley, CA 94720
Citations
========================================================================
.. [TEP_1] TEP 1
<http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-1.html>
.. [TEP_2] TEP 2
<http://www.tinyos.net/working_groups/tinyos-2.0wg/teps/tep-2.html>
.. [Doxygen] Doxygen <http://www.doxygen.org>
.. [Java_Coding_Convention] Java Coding Convention
<http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html>
.. [JavaDoc] JavaDoc <http://java.sun.com/j2se/javadoc>
.. [nesdoc] nesdoc <http://www.tinyos.net/tinyos-1.x/doc/nesc/nesdoc.html>
-------------- next part --------------
_______________________________________________
Tinyos-2.0wg mailing list
Tinyos-2.0wg at Mail.Millennium.Berkeley.EDU
https://mail.millennium.berkeley.edu/cgi-bin/mailman/listinfo/tinyos-2.0wg
More information about the Tinyos-host-mote-wg
mailing list