Re: function name prefixes

[John Darrington]

On Wed, Jan 31, 2007 at 09:56:12PM -0800, Ben Pfaff wrote:
     The convention we've been using in PSPP, which is a common one
     across much free and non-free software, is that each function's
     name should begin with a prefix that is common across every
     function in the given module (typically a single source file).  I
     like this.
     
     However, there's one technical detail about it that's been
     bugging me lately.  When a module name is more than one word,
     sometimes we'll use an underscore in the prefix, e.g. val_labs,
     any_reader, case_source.  Other times, we'll just smash the words
     together, e.g. casereader, casefile, casefilter.

One of the problems here, that how many words there are to a name
is controversial.  Written English prose is slowly becoming more like
German, with a multitude of long compound nouns.  Whereas fifteen
years ago one would have seen "file name", today "filename" is more
common. Similarly, "email" used to be "e-mail" (I think Knuth has
something about this on his home page), "down load" is now "download"
... the list goes on.    Generally, when a multi-word term becomes very
familiar people tend to contract it into one, especially when the
second word starts with an unvoiced consonant.  I think this is what
has happened with case{file,reader,filter}, whereas "vallabs" would be
unpronouncable. It's a rather subjective decision as to how many words
comprise a term, and different conventions tend to prevail on
different sides of the Pacific/Atlantic ocean. 

     I can see an argument for each choice.  Underscores make it
     easier to pick out the words in the module name.  However,
     underscores make the full name longer and, worse (in my opinion),
     underscores can make it hard to visually distinguish the prefix
     from the rest of the function name.


The GNU coding standards say something about this: 
 http://www.gnu.org/prep/standards/standards.html#Names
but you will probably realise that many gnu projects (notably gtk)
 doesn't follow them in all instances.

     What do you guys like better?

Personally I think that hyphens are best, but that's not possible in C
(rewrite PSPP in lisp?), but can still be done for file names (should
that be filenames?) and for some identification strings, such as ids
in glade.  Where hyphens are not possible, I think words should be
seperated by underscores, but if there's a general concensous that a
term is commonly written as a compound word, then just omit the
separating character.

This is what I've been doing, except in the GUI code, where I've been
trying to follow the GTK conventions:
 http://developer.gnome.org/doc/API/2.0/gobject/gtype-conventions.html
Thus, in the GUI objects (things derived from g_object) are prefixed
with "psppire_" for function names, "psppire-" for filenames,
"Psppire" for type names and "PSPPIRE_" for macro names.  For ids in
glade, I've been experimenting with a few conventions, and the one I'm
currently favouring is hyphens for word separators, and underscores to seperate 
things which might be considered namespace components.

     As another scheme I've seen, one place I've worked uses
     capitalization to separate words, with a single underscore
     between module name and function name,
     e.g. ModuleName_FunctionName.  This style would clash badly with
     GNU code, though, so I wouldn't want to use it in PSPP.

I've only ever seen that sort of thing in C++ code.  In Gtk similar
thing is done for function types and I've continued that convention in
src/ui/gui


I think there's no easy answer.  On the one hand I've found some
advantages to the GTK way of doing things, but sometimes it just gets
annoying with function names like
"gtk_tree_model_filter_convert_path_to_child_path". Whichever
convention(s) we decide to follow, let's not be too dogmatic about
them.  If we have a function name prefixed with "casereader_" then all
the public functions in that file should have the same prefix. But I'm
not going to be too upset if there's another file which has
"storage_source_" prefices. 

J'

-- 
PGP Public key ID: 1024D/2DE827B3 
fingerprint = 8797 A26D 0854 2EAB 0285  A290 8A67 719C 2DE8 27B3
See http://pgp.mit.edu or any PGP keyserver for public key.

signature.asc
Description: Digital signature