On Sun, 24 Jun 2007 17:23:52 +0200, neimad <[EMAIL PROTECTED]> 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
-------------------------------------------------------------------------
This SF.net email is sponsored by DB2 Express
Download DB2 Express C - the FREE version of DB2 express and take
control of your XML. No limits. Just data. Click to get it now.
http://sourceforge.net/powerbar/db2/
_______________________________________________
tux-droid-user mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/tux-droid-user
