Re: [tuxdroid-user] Naming functions

[David B. <da...@ja...>]

On Sun, 24 Jun 2007 17:23:52 +0200, neimad <ror...@gm...> wrote:

> Hello,
>
> The naming of functions is currently very inconsistent: some are verbs
> (orders), some are nouns; some have a prefix, some have a suffix --
> some have both, and some have neither.
>
> For example: tux_connection() is a noun but connect_to_tux() is an
> order, id_request() is prefixed while wakeup_tux() is suffixed. These
> last two functions both take an id but one has "id" in its name and
> the other has "tux"...
>
> Imo, all functions should be _verbs_ in the imperative form: functions
> are *orders* given to the machine. It's the usual naming scheme for
> english code.
>
> I think a good convention is also to prefix functions with the type of
> object they act upon. Say I have a type dongle_t; then, connecting to
> a dongle would be done with dongle_connect().
>
> What about send_usb_tux_cmd() ? Does it "send a 'usb tux' command" ?
> If so, what does that mean ? I have a really hard time trying to
> figure out what functions do from their name.
>
> We really need to define some consistent naming conventions for types,
> variables and functions...
>
I completely agree with you here but I have really no experience with  
naming practices. So just give me the name of a couple of functions you're  
not sure about, I'll try to describe them correcty so you can show us some  
good names.

Here are the connection functions I wrote and some description of them:

- disconnect_from_tux()
   Disconnect from a tux (only one is connected so we don't need to pass  
any parameter)

- connect_to_tux(id)
   Connect to a tux which has the id given as parameter

- random_tux_connection()
   Connect to the first tux found around, that's the same behavior as the  
connection we have now in the daemon, we can't choose which tux we want to  
connect to, so this is random.

- id_request(*id)
   Returns the id (as pointer) of the tux you're connected to. (That may  
sound stupid as you had to give the id to connect, but another application  
running on the same daemon/tux will not know it. And if your application  
is restarted, the connection will stay but you may loose the id.)

- id_lookup(*id)
   Returns the id (pointer) of the first tux found around

- change_id(id)
   Chenge the id of a disconnected tux to the id given as parameter

- wakeup_tux(id)
   Wake-up the tux with the id given as parameter

- avoid_wifi_channel(wifi_channel)
   Avoid the frequencies of a wifi_channel, tux will use all the other  
frequencies except those used by the given wifi_channel.


A few extra questions and points:

- should all these functions return an int that indicates if there's an  
error or not?

- if so, should we do it also for functions that can't catch an error  
right now, just to ease the future in case we can add an error check  
later. I guess that makes sense only if we know it's possible to add such  
a check later;

- you can also give some recommendations for the name of parameters (like  
wifi_channel) and variables while we're at it. What about wakeup or  
wake_up or wake-up?

- is "int id_lookup(*id)" a good way to return both the id and if the  
command succeeded or not? That's something I copied from some unix  
functions;

- should we return 0 if successful, -1 otherwise in all functions? Some of  
them return 0 if failure and 1 if success, ... I guess we should be  
consistent here too

- thanks again for taking care of the sanity of the code ;-)

David