"David Bourgeois" <[EMAIL PROTECTED]> writes:
[...]
> - disconnect_from_tux()
> - connect_to_tux(id)
> - random_tux_connection()
> - id_request(*id)
> - id_lookup(*id)
> - change_id(id)
> - wakeup_tux(id)
> - avoid_wifi_channel(wifi_channel)
The naming of these particular functions isn't bad per se, but if we
want to be consistent throughout the code, we should pick a naming
convention.
Taking the above functions as examples, I think I'd name them:
tux_disconnect()
tux_connect()
tux_connect_random()
tux_id()
tux_lookup()
tux_change_id()
tux_avoid_wifi_channel() or dongle_avoid_wifi_channel() [depending
on *what* exactly will avoid using the channel: is it the dongle or
tux ?]
All these functions work on a "tux" object (albeit abstract, as we
don't currently have any data structure representing a tux), hence
their tux_ prefix.
tux_connect() could be connect_to_tux(), as it doesn't have yet a "tux
object" to act upon and instead it does return/find such an object. If
I take an example using files:
file_t *open_file(const char *filename)
This function doesn't act on a file_t object but returns one and thus
doesn't have the file_ prefix, but
int file_write(file_t *file, void *data, size_t size)
acts on a file_t object and thus is prefixed with file_. Or we may
just decide that open_file() would be better named file_open(), since
it's in a "file" module (my preference). And so on...
(Notice too that the file_t parameter is always first.)
We can have very strict naming conventions, or we can give some slack,
but currently the naming is almost random ;-) I prefer very strict
naming conventions, because then you don't even have to ask yourself
"what was the name of that function again ?": if you have a file, of
type file_t, then you now all ops on it start with file_. Same goes
for variables and constants (say, FILE_MODE_RO, FILE_MODE_RW...).
Btw, if I have an enum about the file access modes, I'd name it as
follows (file_mode prefix for the type and its values):
typedef enum {
FILE_MODE_RO,
FILE_MODE_RW
} file_mode_t;
> - should all these functions return an int that indicates if there's
> an error or not?
Not necessarily. Sometimes it's just more convenient to have special
values meaning error (for example, >= 0 might be the number of bytes
while < 0 is an error).
But this is not always possible nor desirable. I don't really have
rules here, I just pick what I think is best...
> - 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;
No, that's "overdesign", kinda. And all your code will have to manage
non-existent errors everywhere you call these functions, all for
nothing.
> - 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?
I don't have any recommendation for the naming of parameters, except
that they should make as obvious as possible what they are, of course.
> - 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;
Yes, it's alright.
Going back to your first question: this is a case were it may be
possible to return a special value for errors, depending on the actual
type of id: if it's signed, the usual convention "< 0 means error"
could be used, but if it's unsigned and zero is a valid id value, then
you can't and you must write the function as you did.
Having special values may also simplify the code a lot: if we can have
a special value ID_NONE to mean "no id", then there's no need to have
both an id value and a boolean telling whether the id is actually set.
> - 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
Well, those functions that return 1 on success and 0 on failure should
really return true and false, respectively. Here too, it all depends
on how much consistent we want to be.
Imho, a module (say, USBDaemon_log.c) should use the same convention
for all its functions as much as possible. Different conventions for
different modules might be perfectly legit, though.
Damien
-------------------------------------------------------------------------
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
