[Tinyos-beta-commits] CVS: tinyos-1.x/beta/teps/txt tep3.txt, 1.3,
1.4
Ion Yannopoulos
ion- at users.sourceforge.net
Fri Feb 25 18:16:33 PST 2005
Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/txt
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv6047/txt
Modified Files:
tep3.txt
Log Message:
Wrap columns at ~72 characters (less than 80).
Index: tep3.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/txt/tep3.txt,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** tep3.txt 25 Feb 2005 20:26:17 -0000 1.3
--- tep3.txt 26 Feb 2005 02:16:31 -0000 1.4
***************
*** 25,40 ****
.. 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.
--- 25,43 ----
.. 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.
***************
*** 45,56 ****
-------
! - Avoid the use of acronyms and abbreviations that are not well known. Try not to
! abbreviate "just because".
! - 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.
--- 48,61 ----
-------
! - Avoid the use of acronyms and abbreviations that are not well known.
! Try not to abbreviate "just because".
! - 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.
***************
*** 58,69 ****
--------
! 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 directory, though a package is most often a directory with
possible subdirectories.
! It should be possible to easily identify what package a name is in. Some languages have
! builtin support for packages, but nesC and C do not, so some conventions will be suggested
! to keep packages coherent.
--- 63,75 ----
--------
! 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 directory, though a package is most often a directory with
possible subdirectories.
! It should be possible to easily identify what package a name is in.
! Some languages have builtin support for packages, but nesC and C do not,
! so some conventions will be suggested to keep packages coherent.
***************
*** 71,93 ****
-------------------
! - Each package should have it's own directory. It may have as many subdirectories as
! are necessary.
! - Each package should have a name, to be used as a prefix to identify it in code.
! This should usually be the same as the directory name, or very close to it.
Any further namespacing is optional.
- Each directory should have a README.
- The default packages in a TinyOS distribution are at least:
! - `tos/system/`. Core TinyOS components. This directory is what's necessary for TinyOS
! to actually run. [Should this be tos/components?]
! - `tos/interfaces/`. Core TinyOS interfaces, including hardware-independent abstractions.
! - `tos/platforms/`. Contains code specific to mote platforms, but chip-independent.
! - `tos/chips/`. Contain code specific to particular chips
! and to chips on particular platforms.
! - `apps/`, `apps/demos`, `apps/tests`, `apps/tutorials`. Contain applications
! with some division by purpose.
! - 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.
--- 77,102 ----
-------------------
! - Each package should have it's own directory. It may have as many
! subdirectories as are necessary.
! - Each package should have a name, to be used as a prefix to identify
! it in code. This should usually be the same as the directory name,
! or very close to it.
Any further namespacing is optional.
- Each directory should have a README.
- The default packages in a TinyOS distribution are at least:
! - `tos/system/`. Core TinyOS components. This directory is what's
! necessary for TinyOS to actually run. [Should this be tos/components?]
! - `tos/interfaces/`. Core TinyOS interfaces, including
! hardware-independent abstractions.
! - `tos/platforms/`. Contains code specific to mote platforms, but
! chip-independent.
! - `tos/chips/`. Contain code specific to particular chips and to
! chips on particular platforms.
! - `apps/`, `apps/demos`, `apps/tests`, `apps/tutorials`. Contain
! applications with some division by purpose.
! - 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.
***************
*** 101,188 ****
.....
! - All nesC files have a `.nc` extension. The filename must match the interface or
! component name (the compiler requires it).
! - Interface and component names should be mixed case, starting upper case, prefixed by package.
- All configurations should be suffixed with 'C'.
- All modules should be suffixed with 'M'.
- Avoid interfaces ending in 'C' or 'M'.
! - If an interface and component are related it is useful if they have the same name
! except for the suffix of the component.
! - Any public module should have a similarly named configuration. Wiring in a configuration
! should only be done to other configurations, to this module, or to private components.
! - 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` numeric 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.
! They should be distinguishable from local variables: the recommended practice
! is to prefix them with `\m_`.
Packages
........
! - nesC protects all C names declared in it with the component name. The only names that
! can collide in nesC are interfaces and components. Thus only these need package prefixes.
! - Public interfaces and components must have a prefix indicating which package they belong to.
! Names are chosen as follows:
- The TinyOS core (i.e. in `system/`) has no prefix.
! - A platform, library, or application (e.g. `MSP430`, `Deluge`, `Mate`) should have a prefix
! which matches the directory name.
! - All HAL [TEP_2]_ interfaces and components are public to their platform, and should be prefixed
! with their platform.
! - Private interfaces and components do not necessarily need a prefix. However given that
! each component is in the same namespace as every other component in all packages, and possible
! ambiguity with overridden components (see below), it is advised that a prefix be used anyway.
! - All HPL [TEP_2]_ interfaces and components are private to their platform and so do not need
! the package prefix. They should however be prefixed with the letters 'HPL'.
! - It is permissible to have the same name as a component in another package if the purpose
! of the component is to act as a replacement for the original component (e.g. because the
! same interface has a different implementation on each platform.)
! - A HIL [TEP_2]_ interface or component is platform independent but needs to wire to particular
! platform implementations to work. HIL components therefore have the same name under
! different platforms, as only one of them will be used.
Extra
.....
! - Don't use `#include` in `.nc` files. Use the nesC `includes` statement instead.
! - Don't declare macros in `.nc` files. Put them in an associated C header file.
- `#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 [*].
! The filename should be similar or identical to the nesC component which uses it.
! [*] Note that the only way to access C source in nesC is to `#include` it:
! nesC programs do not link in external C code, in order to allow inlining.
! - C does not protect names in any way, so all names should be package prefixed. This means
! all types, functions, variables, and constants. 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 (`struct`, `enum`, or `typedef`) should be lower case, words separated by
! underscores, prefixed by package, and ending in `'_t'`.
! - Functions should be lower case, words separated by underscores, prefixed by package.
! - Function macros should be all upper case, words separated by underscores,
prefixed by package.
- Use of function macros is discouraged: use inline functions.
! - Constants should be all upper case, words separated by underscores, prefixed by package.
- Use of `#define` numeric constants is discouraged: use `enum`.
--- 110,215 ----
.....
! - All nesC files have a `.nc` extension. The filename must match the
! interface or component name (the compiler requires it).
! - Interface and component names should be mixed case, starting upper
! case, prefixed by package.
- All configurations should be suffixed with 'C'.
- All modules should be suffixed with 'M'.
- Avoid interfaces ending in 'C' or 'M'.
! - If an interface and component are related it is useful if they have
! the same name except for the suffix of the component.
! - Any public module should have a similarly named configuration. Wiring
! in a configuration should only be done to other configurations, to this
! module, or to private components.
! - 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` numeric 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.
! They should be distinguishable from local variables: the recommended
! practice is to prefix them with `\m_`.
Packages
........
! - nesC protects all C names declared in it with the component name.
! The only names that can collide in nesC are interfaces and components.
! Thus only these need package prefixes.
! - Public interfaces and components must have a prefix indicating which
! package they belong to. Names are chosen as follows:
- The TinyOS core (i.e. in `system/`) has no prefix.
! - A platform, library, or application (e.g. `MSP430`, `Deluge`, `Mate`)
! should have a prefix which matches the directory name.
! - All HAL [TEP_2]_ interfaces and components are public to their
! platform, and should be prefixed with their platform.
! - Private interfaces and components do not necessarily need a prefix.
! However given that each component is in the same namespace as every
! other component in all packages, and possible ambiguity with overridden
! components (see below), it is advised that a prefix be used anyway.
! - All HPL [TEP_2]_ interfaces and components are private to their
! platform and so do not need the package prefix. They should however
! be prefixed with the letters 'HPL'.
! - It is permissible to have the same name as a component in another
! package if the purpose of the component is to act as a replacement
! for the original component (e.g. because the same interface has a
! different implementation on each platform.)
! - A HIL [TEP_2]_ interface or component is platform independent but
! needs to wire to particular platform implementations to work. HIL
! components therefore have the same name under different platforms,
! as only one of them will be used.
Extra
.....
! - Don't use `#include` in `.nc` files. Use the nesC `includes`
! statement instead.
! - Don't declare macros in `.nc` files. Put them in an associated C
! header file.
- `#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 [*].
! The filename should be similar or identical to the nesC component
! which uses it.
! [*] Note that the only way to access C source in nesC is to `#include`
! it: nesC programs do not link in external C code, in order to allow
! inlining.
! - C does not protect names in any way, so all names should be package
! prefixed. This means all types, functions, variables, and constants.
! 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 (`struct`, `enum`, or `typedef`) should be lower case,
! words separated by underscores, prefixed by package, and ending in
! `'_t'`.
! - Functions should be lower case, words separated by underscores,
prefixed by package.
+ - Function macros should be all upper case, words separated by
+ underscores, prefixed by package.
- Use of function macros is discouraged: use inline functions.
! - Constants should be all upper case, words separated by underscores,
! prefixed by package.
- Use of `#define` numeric constants is discouraged: use `enum`.
***************
*** 193,197 ****
---------------
! - The standard Java coding convention [Java_Coding_Convention]_ should be followed.
- All code declared for core TinyOS is in the package `net.tinyos`.
--- 220,225 ----
---------------
! - The standard Java coding convention [Java_Coding_Convention]_
! should be followed.
- All code declared for core TinyOS is in the package `net.tinyos`.
***************
*** 215,223 ****
========================================================================
! .. [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>
--- 243,253 ----
========================================================================
! .. [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>
More information about the Tinyos-beta-commits
mailing list