Author: sebastien.lelong
Date: Fri Oct 24 12:03:50 2008
New Revision: 459
Modified:
wiki/JallibStyleGuide.wiki
Log:
test & board files naming convention
include "device family" concept
Modified: wiki/JallibStyleGuide.wiki
==============================================================================
--- wiki/JallibStyleGuide.wiki (original)
+++ wiki/JallibStyleGuide.wiki Fri Oct 24 12:03:50 2008
@@ -92,11 +92,17 @@
=== Filenames ===
-A library must be named as *`<function>_<device>.jal`*. _function_ gives
clues about what the library is about. Then _device_ precisely sets the
part involved.
+A library must be named as:
+
+ * *`<function>_<implementation|other>.jal`* for PIC-specific libraries
(peripherals). _function_ gives clues about what the library is about. Then
_implementation_ or _other_ is here to differentiate libraries, and is more
about implementations (`serial_hardware.jal`, `serial_software.jal`),
things specific to the function (`pwm_ccp1.jal`, `pwm_ccp2.jal`, ...).
+
+ Ex: `serial_hardware.jal`, `serial_software.jal`, `pwm_ccp1.jal`.
+
+ * *`<device-family>_<device>.jal`* for external libraries.
_device-family_ describes the device family (...), and is often the
directory name where the lib is. _device_ precisely sets the part.
+
+ Ex: `lcd_hd44780_4.jal`, `rtc_ds1302.jal`, `co2_t6603.jal`
-This naming convention is particularly true when libraries are
for "external" map, that is for external parts, not PIC. For example,
`co2_t6603.jal` is a library used to deal with t6603 chip, used to measure
CO2 gaz levels. Easy !
-For PIC-specific libraries, _device_ is more about implementations
(`serial_hardware.jal`, `serial_software.jal`), things specific to the
function (`pwm_ccp1.jal`, `pwm_ccp2.jal`, ...).
=== Constants, variables, procedures, functions ===
@@ -105,29 +111,43 @@
Variables, constants, procedures and functions must be named as:
* *`<device>_<whatever>`* if you want to avoid namespace collision
- * *`<function>_<whatever>`* if you want to have a common API
+ * *`<device-family>_<whatever>`* if you want to have a common API
For example, co2_t6603.jal library have all its procedures starting with
`t6603_` (and `_t6603_` for internal names). This makes all these
procedures very specific to this library. If you have another CO2 sensor,
you'll be able to use both at the same time, because they'll be no
namespace collision. This is the purpose of the `<device>_<whatever>`
naming convention.
-Another example: the names of the procedures in the LCD libaries start
with `lcd_` (and `_lcd_` for internal names). There are many different LCD
types, but all implements the same API, because procedures, variables,
etc... are named according to the function, not the device. This is the
purpose of the `<function>_<whatever>` naming convention.
+Another example: the names of the procedures in the LCD libaries start
with `lcd_` (and `_lcd_` for internal names). There are many different LCD
types, but all implements the same API, because procedures, variables,
etc... are named according to the device-family, not the device itself.
This is the purpose of the `<device-family>_<whatever>` naming convention.
Now, how do you know which to follow ? Ask, we'll discuss...
+Note:
+following the same principle, naming const/var/procdecure/function in a
PIC-specific libraries (peripherals) can include the _function_ and/or the
_implementation_. This depends whether you want to have more than one
function within a same PIC.
+
+Ex: There are two implementations of i2c and serial: hardware and
software. Having both i2c implementation within a same PIC is not useful,
since i2c is adressable. Thus, all const/var/... are prefixed by
`i2c_<whatever>.jal`. On the contrary, it can be useful to have two serial
implementation within a same PIC (eg. one talking a PIC, another talking to
a external device). Thus, serial libs' const/var/... are prefixed by
`serial_hw_<whatever>.jal` or `serial_sw_<whatever>.jal`.
+
+
=== Pin names ===
The pins are named as:
* *`<device>_<external_pin_name>`* if you want to avoid namespace
collision
- * *`<function>_<external_pin_name>`* if you want to have a common API
+ * *`<device-family>_<external_pin_name>`* if you want to have a common API
-This is almost the same as for variables, contants, ... except the
`<whatever>` part now corresponds the pin name of the external device
(usually found in datasheets). Using the `<function>_<external_pin_name>`
convention to build a common API may cause problems, if pin names aren't
named the same in all supported devices. In that case, the pin name should
be as explicit as possible...
+This is almost the same as for variables, contants, ... except the
`<whatever>` part now corresponds the pin name of the external device
(usually found in datasheets). Using the
`<device-family>_<external_pin_name>` convention to build a common API may
cause problems, if pin names aren't named the same in all supported
devices. In that case, the pin name should be as explicit as possible...
_See also the very important rules about pin names within a
library: "Don't use port and pin names"_
+=== Samples and tests ===
+
+Tests are named as `test_<whatever>.jal`. That is, they should starts with
the prefix `test_`. That is, samples must *not* start with `test_`.
+
+Board files are named as `board_<pic>_<whatever>.jal`
+
=== Why such a pain ?... ===
-The main purpose of this is to control the naming conflicts between
libraries and application code. Bear in mind that this is about
source-level libraries which are combined by the compiler to form a single
application program.
+The main purpose of this is to control the naming conflicts between
libraries and application code. Bear in mind that this is about
source-level libraries which are combined by the compiler to form a single
application program.
+
+Having naming convention is also a great optimize process, saving time, by
scripting and generating code. This is good.
== Don't use port and pin names ==
--~--~---------~--~----~------------~-------~--~----~
You received this message because you are subscribed to the Google Groups
"jallib" group.
To post to this group, send email to [email protected]
To unsubscribe from this group, send email to [EMAIL PROTECTED]
For more options, visit this group at
http://groups.google.com/group/jallib?hl=en
-~----------~----~----~----~------~----~------~--~---
