vote on namespace for procedures and functions

[Eur van Andel]

Hi

We need a vote about procedure names.

NB: names for libraries and pins are already settled, see:

Rules of thumb

Filenames, variables, procedures naming convention

Filenames

in:

http://code.google.com/p/jallib/wiki/JallibStyleGuide

I see several possibilities:

--------------------------------------------------------------------------------------

1) device_function()

examples:

hd44780_clear(), hd44780_line1, hd44780'put()

t6603_read_co2(), t6603_read_height()

tc77_read_celsius(), tc77_read_fahrenheit

--------------------------------------------------------------------------------------

2) function_device()

examples:

clear_lcd_hd44780(), lcd_set_cursor_hd44780(), lcd_hd44780'put()

read_co2_t6603(), read_height_t6603()

read_celsius_tc77(), read_fahrenheit_tc77()

--------------------------------------------------------------------------------------

3) function()

examples:

clear_lcd(), lcd_set_cursor(), lcd'put()

read_co2(), read_height()

read_celsius(), read_fahrenheit()

--------------------------------------------------------------------------------------

1) pro: no namespace collision

1) con: not too clear if you don't know the IC numbers, long, oldskool

2) pro: no namespace collision, can be changed to another device by replacing chip number

2) con: long

3) pro: short, simple

3) con: namespace collision, unclear which external device is used

We could cheat and use both 2 and 3: I like put/get functions for lcd and serial. And yes, you will need to hack the library if you want to use two lcds and rename one putfunction "lcd2" for instance. 

My vote: 2) with putfunctions (and only put/get functions) like 3). 

Your votes please. 

---

ir EE van Andel e...@fiwihex.nl  http://www.fiwihex.nl

Fiwihex B.V. Wierdensestraat 74, NL7604BK Almelo, Netherlands

tel+31-546-491106 fax+31-546-491107

[Sebastien Lelong]

You do not specify all what is said in JSG (avoid namespace collision vs. Common API, for instance). Names for libraries and pins are already settled, as procedures, function, etc..

I vote for what is in JSG...

Seb

---

De: Eur van Andel <e...@fiwihex.nl>
Env: mardi 14 octobre 2008 23:34
À: jallib <jal...@googlegroups.com>
Objet: [jallib] vote on namespace for procedures and functions

Hi

We need a vote about procedure names.

We could cheat and use both 2 and 3: I like put/get functions for lcd and serial. And yes, you will need to hack the library if you want to use two lcds and rename one putfunction "lcd2" for instance. 

My vote: 2) with putfunctions (and only put/get functions) like 3). 

Your votes please. 

---

ir EE van Andel e...@fiwihex.nl  http://www.fiwihex.nl

[Sebastien Lelong]

Few more words.

About examples: if device_function() gives hd44780_clear(), then function_device() should give clear_hd44780(), not clear_lcd_hd44780()

If you go with 2), how will you deal with common API ? Since you put the device (hd44780), what will you do when you'll change the LCD type (st7036) ? Isn't this why we don't use "device", but what we call "function" (lcd) and may call "device_family" or something else. I understand there's a confusion about the meaning of "function", better reserved for proc/func name, such as "read", "write", "print", "move_motor_forward", etc...


Seb

PS: I still vote for what is in the JSG :)

2008/10/14 Eur van Andel <e...@fiwihex.nl>

[Eur van Andel]

On 15 Oct 2008, at 01:54 , Sebastien Lelong wrote:

You do not specify all what is said in JSG (avoid namespace collision vs. Common API, for instance). Names for libraries and pins are already settled, as procedures, function, etc..

I vote for what is in JSG...

The JSG is not consistent:

procedures and functions must be named as:

    * <function>_<whatever> if you want to have a common API 

is not the same as:

All external names (of global variables, constants, procedures and functions available to application programs) must start with a prefix unique to the library. 

because "function" can't be (and shouldn't be) specific to a library. Enforcing both these rules (function_whatever + specific start) would mean:

get_temp_celsius() -- tc77 temp

read_temp_celsius() -- tc74 temp

haul_temp_celsius() -- ds1820 temp

where get, read and haul woudl be specific to their respecitve libraries. This is bad. 

---

ir EE van Andel e...@fiwihex.nl  http://www.fiwihex.nl

[Sebastien Lelong]

The JSG is not consistent:

procedures and functions must be named as:

    * <function>_<whatever> if you want to have a common API 

is not the same as:

All external names (of global variables, constants, procedures and functions available to application programs) must start with a prefix unique to the library. 

because "function" can't be (and shouldn't be) specific to a library

If all vars, consts, procs, funcs in a library start with "blabla_", don't we have a prefix unique to the library ?

As I said a previous post today, the main confusion seems to come from the meaning of "function". You consider function as "get", "read", "write", etc... I consider function as "lcd", "temperature", "i2c", "serial", etc... Maybe, for what I mean, "device_family" should be better.


Seb
 

[Eur van Andel]

On 15 Oct 2008, at 09:41 , Sebastien Lelong wrote:

The JSG is not consistent:

procedures and functions must be named as:

    * <function>_<whatever> if you want to have a common API 

is not the same as:

All external names (of global variables, constants, procedures and functions available to application programs) must start with a prefix unique to the library. 

because "function" can't be (and shouldn't be) specific to a library

If all vars, consts, procs, funcs in a library start with "blabla_", don't we have a prefix unique to the library ?

We do. It is neither a function nor a device.

As I said a previous post today, the main confusion seems to come from the meaning of "function". You consider function as "get", "read", "write", etc... I consider function as "lcd", "temperature", "i2c", "serial", etc... Maybe, for what I mean, "device_family" should be better.

Both are functions. 

Methinks that the device specific part should be as descriptive to the device as possible, like chip numbers or _hardware / _software for a serial lib. 

[Eur van Andel]

On 15 Oct 2008, at 08:13 , Sebastien Lelong wrote:

About examples: if device_function() gives hd44780_clear(), then function_device() should give clear_hd44780(), not clear_lcd_hd44780()

If you go with 2), how will you deal with common API ? Since you put the device (hd44780), what will you do when you'll change the LCD type (st7036) ? Isn't this why we don't use "device", but what we call "function" (lcd) and may call "device_family" or something else. I understand there's a confusion about the meaning of "function", better reserved for proc/func name, such as "read", "write", "print", "move_motor_forward", etc...

Device family, I like that. I'll think about it some more.