Choosing a name/codename for your project

[Javier Lopez]

This isn't a C-only question, but I like to name my functions or globals
prepending the project name to avoid namespace pollution as in:
void libunknown_dosomething(void);

So, what's the best practice, thinking of a codename (deferring the task
of choosing the final name) and prepend it where needed or choosing a
project name early and use it consistently through the code?

In either case, I have an open question: how do you choose a project

name?

I got some inspiration from RFC 1178 (choosing a good hostname): use
theme names, but I don't know if any of you have a better method.

Thanks!

 

[Jorgen Grahn]

This isn't a C-only question, but I like to name my functions or globals
prepending the project name to avoid namespace pollution as in:
void libunknown_dosomething(void);

If I'm not writing a reusable library (which I almost never do) I try
to avoid that[0]. Let the libraries you use do their prefixing thing,
and enjoy the luxury of giving your things simple names.

(They won't be that simple anyway, since you'll often end up with the
argument type as part of the name, e.g. list_is_empty() versus
house_is_empty().)

In either case, I have an open question: how do you choose a project

name?[/QUOTE]

With difficulty.

/Jorgen

[0] In C++ I do it more often, but then I use namespaces, and they
lack many of the drawbacks of "manual" prefixing.

 

[glen herrmannsfeldt]

This isn't a C-only question, but I like to name my functions or globals
prepending the project name to avoid namespace pollution as in:
void libunknown_dosomething(void);

So, what's the best practice, thinking of a codename (deferring the task
of choosing the final name) and prepend it where needed or choosing a
project name early and use it consistently through the code?

Seems to me that this is what Java packages are supposed to solve.

I haven't written them all that often, so I might not get the details
right, but you put a package statement at the top, and everything
in the class is automatically qualified with that name. If you
want to change it, you only change it in one place. (Actually more than
one, the name has to match the directory that it is in.)

There is also the convention that the name start with your domain
name with the qualifiers in the reverse order. That is, all the
standard Java packages start with com.sun.

When you use them, you can reference them with the fully qualified
name, but more usual you use the import statement which, if the names
are unique, allows you to write them without qualification. In the
unfortunate case where they are not unique and referenced from the
same class, you have to qualify each reference.

-- glen

 

[BGB]

On 3/18/2014 2:45 PM, Javier Lopez wrote:> This isn't a C-only question,
but I like to name my functions or globals

prepending the project name to avoid namespace pollution as in:
void libunknown_dosomething(void);

So, what's the best practice, thinking of a codename (deferring the task
of choosing the final name) and prepend it where needed or choosing a
project name early and use it consistently through the code?

In either case, I have an open question: how do you choose a project

name?

I got some inspiration from RFC 1178 (choosing a good hostname): use
theme names, but I don't know if any of you have a better method.
[/QUOTE]

generally, I name libraries basically using abbreviation of various
things combined together into acronyms.

ex: BGB (myself), Tech -> BGB+Tech -> BT,
Game Engine -> GE
Server -> SV

BT+GE+SV -> BTGESV
likewise, BTGECM, ...

sometimes, there are variations, like:
'BGBBTJPG' for my main graphics/image library, its name being mostly
because it started out mostly as a library specifically for an extended
JPEG variant, but basically expanded to a mass of image-loaders and
video-codecs and logic for working with various compressed texture
formats and similar.

and, my 3D renderer is called "LBXGL" originally meaning "Lang/BGB
eXtensions for OpenGL", where "Lang/BGB" was an earlier name for my
script-language efforts, but later coalesced into a language I call
"BGBScript", with a VM backend with parts named as "BSVMC" ("BGBScript
VM Compiler"), "BSVMI" ("BGBScript VM Interpreter"), ...

likewise, "BGBGC" and "BGBDY" for "BGB Garbage Collector" and "BGB
Dynamic" (the dynamic-types library, actually serves as a pretty major
hub for the "VM sub-project", and by extension pretty much the entire
engine-codebase).


then names are generally formed as:
LIBNAME_SubSystem_Function
or:
LIBNAME_SubSystem_Function_SubFunction
and sometimes:
LIBNAME_SubSystem_FunctionSUFFIX
or:
LIBNAME_SubSystem_Function_SubFunctionSUFFIX

where subsystem refers to various subdivisions within a given library,
for example:
BGBBTJPG_BC7_...	//stuff for BC7 texture-compression
BGBBTJPG_BT1C_...	//stuff for the BTIC1C video codec
....

sub-function is when a given functions' logical operation needs to be
broken up into multiple functions for some reason, generally not
intended to be used by itself.

suffixes are typically multi-letter codes that indicate special
properties or variants of a functions' logical operation.

function names are typically on of:
VerbSubject
VerbSubjectObject
VerbSubjectSubClauses

such as:
AllocSomething
FreeSomething
DoSomethingWithSomethingElse
....


often:
LIBNAME_Function
is user for library level functions (exported API) whereas typically
subsystem-qualified names are considered internal to the library (and
are very often not exported).

another variant is having the name lower-case, ex:
libname_subsys_someFunction

which generally means "this function is private, don't use".


sometimes:
"pfxSomeFunction" is used for "formal APIs", which are basically public
APIs functions intended to be used as part of the core project
infrastructure. generally, these are used sparingly (and in my codebase
the prefixes are typically 3 or 4 letters).


generally, with a lot of this, internal name clashes are avoided, and it
makes keeping track of inter-library dependencies easier.

though, granted, my codebase isn't particularly small, and these
conventions mostly emerged to help deal with scalability issues.


or such...

 

[Fred K]

This isn't a C-only question, but I like to name my functions or globals prepending the project name to avoid namespace pollution as in: void libunknown_dosomething(void); So, what's the best practice, thinking of a codename (deferring the task of choosing the final name) and prepend it where needed or choosing a project name early and use it consistently through the code? In either case, I have an open question: how do you choose a project

name? I got some inspiration from RFC 1178 (choosing a good hostname): use theme names, but I don't know if any of you have a better method. Thanks![/QUOTE]

The convention of using short prefixes has been around for decades.
For example, all methods in the X Windows library begin with a 
capital "X", followed by the function name using camel case with 
initial capital letter, such as XDrawLine().

The X Toolkit library follows the same pattern using the prefix "Xt".

Same with the Motif library, using "Xm".

The Xdt plotting library uses "Xdt" (originally from Dovetail).

 

[BGB]

This isn't a C-only question, but I like to name my functions or globals prepending the project name to avoid namespace pollution as in: void libunknown_dosomething(void); So, what's the best practice, thinking of a codename (deferring the task of choosing the final name) and prepend it where needed or choosing a project name early and use it consistently through the code? In either case, I have an open question: how do you choose a project

name? I got some inspiration from RFC 1178 (choosing a good hostname): use theme names, but I don't know if any of you have a better method. Thanks![/QUOTE]

The convention of using short prefixes has been around for decades.
For example, all methods in the X Windows library begin with a
capital "X", followed by the function name using camel case with
initial capital letter, such as XDrawLine().

The X Toolkit library follows the same pattern using the prefix "Xt".

Same with the Motif library, using "Xm".

The Xdt plotting library uses "Xdt" (originally from Dovetail).
[/QUOTE]


a drawback though with short prefixes though is that there is a small
finite number of them, making clashes (between projects) much more likely.

for example, there are 26 1-letter prefixes, 676 2-letter prefixes, and
17576 3-letter prefixes.

while it may seem like 3-letters is plenty big space, consider for
example, the relative difficulty of finding unused 3-letter
file-extensions, and tendency for many extensions to be used by multiple
apps for different things, ...


with 4 letters, it is 456976 and with 5-letters, it is 11881376, which
is a little better chances that no one will clash (apart from
statistical biases in letter choices or patterns).


capitalization conventions though can help eliminate many clashes
though, effectively causing the prefix-spaces to exist independently.

OTOH, a drawback with longer prefixes is that they add lots of bulk and
length to function names, making them unwieldy and making it more common
to end up resorting to copy/pasting the function names rather than
re-type them (as well as generally looking uglier).


so, it is tradeoffs...

 

[glen herrmannsfeldt]

(snip)

The convention of using short prefixes has been around for decades.
For example, all methods in the X Windows library begin with a
capital "X", followed by the function name using camel case with
initial capital letter, such as XDrawLine().

It goes back at least to OS/360.

Each part of OS/360 has a three letter prefix. The assembler and
linker allow eight character names, so the prefix can't be too long.
All the OS/360 ones start with I (for IBM). I believe that some first
letters are reserved for IBM, and others available.

(Compilers and libraries have separate prefixes, in case that isn't
so obvious.) All messages start with the corresponding prefix, so
you know where to look them up.

I used to think it was the C library with the CEE prefix, but
it seems that it is actually Common Execution Environment, used
by C, but also other compilers.

Internal names don't all have the prefix, but external names
pretty much always do. You don't have to worry about conflicts
when more than one are in the same link library, for example.

-- glen

 

[Michael Angelo Ravera]

This isn't a C-only question, but I like to name my functions or globals
prepending the project name to avoid namespace pollution as in:
void libunknown_dosomething(void);

So, what's the best practice, thinking of a codename (deferring the task
of choosing the final name) and prepend it where needed or choosing a
project name early and use it consistently through the code?

In either case, I have an open question: how do you choose a project

name?

I got some inspiration from RFC 1178 (choosing a good hostname): use
theme names, but I don't know if any of you have a better method.[/QUOTE]

Use a good descriptive name for the project like "MichsExtendedInteger" Library
Use a relatively short, but unique (in your development domain) prefix like "MXI_" Don't include "Library" or "Lib" as part of your prefix.

Best practice would be to register your library prefix with a central authority in your development domain.

If you are distributing an object library, you may want to pre-prefix it with something unique to your environment, like a hexadecimal IP address or the like.

 

[Eric Sosman]

This isn't a C-only question, but I like to name my functions or globals
prepending the project name to avoid namespace pollution as in:
void libunknown_dosomething(void);

So, what's the best practice, thinking of a codename (deferring the task
of choosing the final name) and prepend it where needed or choosing a
project name early and use it consistently through the code?

Other respondents have tackled this question ...

In either case, I have an open question: how do you choose a project

name?[/QUOTE]

... but this one appears not to have been addressed, so I'll
try to help with it.

There are two *essential* characteristics of a good project
name: First, it should be a word or name or short phrase that most
people will recognize (in its pre-project sense), and second, it
should give absolutely no clue as to the nature of the project.
For example, if the project produces statistical tools for time-
series modelling you would call it "Anemone."  If it's software
for 3-D solid printers you'd call it "Sweet Potato."  If it's
a cryptography project you'd call it "Daffodil" because that was
your pet name for a girl friend you never quite understood ("never
understood," "crypto," get it?), but if you ever disclosed the
derivation you'd instantly lose all your developer cred.

That's why we have "Java" and "Mozilla" and "Acrobat" and
"Hadoop" -- and, it must be said, "C."

;-(