[Tinyos-beta-commits] CVS: tinyos-1.x/beta/teps/txt tep3.txt, 1.10,
1.11
David Gay
idgay at users.sourceforge.net
Wed Aug 3 10:45:16 PDT 2005
Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/txt
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv26322
Modified Files:
tep3.txt
Log Message:
coding convention update.
mostly:
- remove strict package prefix rules.
- component suffixes are now C for public, and P for private (ick!?).
Index: tep3.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/txt/tep3.txt,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** tep3.txt 6 Jun 2005 21:28:19 -0000 1.10
--- tep3.txt 3 Aug 2005 17:45:13 -0000 1.11
***************
*** 50,53 ****
--- 50,56 ----
- 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.
***************
*** 69,76 ****
directory with zero or more 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.
Directory structure
--- 72,85 ----
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
***************
*** 79,99 ****
- 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:
!
! - Core TinyOS components, types and interfaces do not have a prefix.
! - Libraries must have a prefix corresponding to their directory name.
! - Applications do not need a prefix but are encouraged to have one.
! - Subdirectories do not need to be incorporated into the prefix.
! - Any further namespacing is optional.
- 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.
- [Should this be `tos/components`?]
- `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/platforms/`. Contains code specific to mote platforms, but
chip-independent.
--- 88,101 ----
- 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.
***************
*** 121,137 ****
.....
! - All nesC files have a `.nc` extension. The filename must match the
! interface or component name (the compiler requires it).
- Directory names should be lowercase.
- 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.
- - Modules are private. To make a module publically available, build a
- configuration for it. 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.
--- 123,136 ----
.....
! - 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.
***************
*** 140,187 ****
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/` and `interfaces/`) has no prefix.
! - A platform, library (e.g. `MSP430`, `Deluge`, `Mate`) should have a
! prefix which matches the directory name.
! - Applications do not need prefixes but large ones are encouraged to
! use one to avoid possible collisions with future core names.
! - 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.
Preprocessor
--- 139,165 ----
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
***************
*** 190,197 ****
- 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 within
! a `module` definition to actually limit their scope to the module.
- Macros which are meant for use in multiple `.nc` files should be
! `#define`'d in an associated C header.
- Use of macros should be minimized:
`#define` should only be used where `enum` and `inline` do not suffice.
--- 168,176 ----
- 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.
***************
*** 204,242 ****
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 shared by a package should have a name with the package
! prefix.
! .. Filenames which are not associated with a component should be lowercase.
! - Directory names should be lowercase.
! - 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 (define with `typedef`) should be lower case, words
! separated by underscores, prefixed by package, and ending in `'_t'`.
- C tag names (for `struct`, `union`, or `enum`) should be lower case,
! words separated by underscores, prefixed by package. Types with tag
! names should provide a typedef with a '_t' extension.
- 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,
! prefixed by package.
- Function macros (`#define` ) should be all upper case, words separated
! by underscores, prefixed by package.
- Using function macros is discouraged: use `inline` functions.
! - Constants should be all upper case, words separated by underscores,
! prefixed by package.
!
! - Use of `#define` for numeric constants is discouraged: use `enum`.
! - Do use `#define` for string constants.
- Global variables should be mixed case, starting lower case.
--- 183,218 ----
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.
***************
*** 247,251 ****
- The standard Java coding convention [Java_Coding_Convention]_
should be followed.
! - All code declared for core TinyOS is in the package `net.tinyos`.
--- 223,227 ----
- The standard Java coding convention [Java_Coding_Convention]_
should be followed.
! - All core TinyOS code is in the package `net.tinyos`.
More information about the Tinyos-beta-commits
mailing list