Author: sebastien.lelong
Date: Thu Oct 9 12:31:30 2008
New Revision: 381
Modified:
wiki/JallibStyleGuide.wiki
Log:
naming conventions.
Modified: wiki/JallibStyleGuide.wiki
==============================================================================
--- wiki/JallibStyleGuide.wiki (original)
+++ wiki/JallibStyleGuide.wiki Thu Oct 9 12:31:30 2008
@@ -88,13 +88,35 @@
= Rules of thumb =
-== External and Internal names ==
+== Filenames, variables, procedures naming convention ==
-All *external names* (of global variables, constants, procedures and
functions available to application programs) *must* start with a prefix
unique to the library. For example the names of the procedures in the
lcd-libaries start with `lcd_`.
+=== Filenames ===
-Names of other global entities (not supposed being used by application
programs) should start with an additional underscore. In the LCD-library
the prefix of internal variables etc. would be `_lcd_`.
+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.
-The main purpose of this is to avoid 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.
+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 ===
+
+All *external names* (of global variables, constants, procedures and
functions available to application programs) *must* start with a prefix
unique to the library. Names of other global entities (not supposed being
used by application programs) should start with an additional underscore.
+
+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
+
+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.
+
+Now, how do you know which to follow ? Ask, we'll discuss...
+
+
+=== 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.
== 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
-~----------~----~----~----~------~----~------~--~---