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
-~----------~----~----~----~------~----~------~--~---

Reply via email to