Function Naming

What kind of naming convension do you guys like the most?

I have been thinking about how to best name functions.

At the moment, all my functions are prefixed with the type of object they manipulate first and then the function they performs like this:

zsSpriteCreate
zsSpriteRemove
zsLayerCreate
zsLayerRemove
zsResourceLoad
zsResourceRemove

But I was thinking that people might prefer having the function first and then the object type after like this:

zsCreateSprite
zsRemoveSprite
zsCreateLayer
zsRemoveLayer
zsLoadResource
zsRemoveResource

What is your prefered way of naming functions?

I just name them something that fits the subject of what the function does (no prefixs or anything of that sort), then after that I usually go overkill on the function overloading when programmin' in Java.

I tend to do it the second way; I have a lot of UpdateWhatever functions. I don't adhere to a really strict naming convention though. The first way is probably better as far as code structuring, but the second way is a lot more natural to read.

class CScriptEngine
{
private:
CScriptEngine( CScriptEngine const& c );
lua_State* state;
bool stateOwned;
 
void post( );
 
public:
// CTOR/DTOR
CScriptEngine( );
CScriptEngine( lua_State* state );
virtual ~CScriptEngine( );
 
// Execution
void DoString( string str );
void DoFile( string file );
 
// Register C function
void RegisterFunction( string name, lua_CFunction f );
 
// Get Globals
inline bool GetGlobalBool( string name );
inline string GetGlobalString( string name );
inline double GetGlobalNumber( string name );
inline void* GetGlobalPointer( string name );
 
// Set Globals
inline void SetGlobalBool( string name, bool b );
inline void SetGlobalString( string name, string s );
inline void SetGlobalNumber( string name, double d );
inline void SetGlobalPointer( string name, void* p );
 
// To TYPE
bool ToBool( int idx=-1 );
string ToString( int idx=-1 );
double ToNumber( int idx=-1 );
void* ToPointer( int idx=-1 );
cTV_3DVECTOR ToVector( int idx=-1 );
cTV_3DQUATERNION ToQuaternion( int idx=-1 );
cTV_COLOR ToColor( int idx=-1 );
 
// Pop a TYPE
inline bool PopBool( );
inline string PopString( );
inline double PopNumber( );
inline void* PopPointer( );
inline cTV_3DVECTOR PopVector( );
inline cTV_3DQUATERNION PopQuaternion( );
inline cTV_COLOR PopColor( );
 
// Pop amnt values off the stack
void Pop( int amnt = 1 );
 
// Push a value onto the stack
void Push( bool b );
void Push( string s );
void Push( double d );
void Push( void* p );
inline void Push( const cTV_3DVECTOR& v );
inline void Push( const cTV_3DQUATERNION& q );
inline void Push( const cTV_COLOR& c );
 
// Modify tables..
void CreateTable( );
void GetTable( int idx );
void SetTable( int idx );
 
// Get the top of the stack (stack size in elements)
int GetTop( );
 
// Call a function
void Call( string name, int numArguments=0, int numResults=0 );
 
// Get and set the state
lua_State* GetState( );
void SetState( lua_State* s, bool free=false );
__declspec( property( get=GetState, put=SetState ) )
lua_State* State;
};

Like that.

getInstance or Create. Everything else is usually methods.

I name things so what when they get used, it's almost like auto-documenting the code at that point.

Actual comments in my code will generally be to explain why something is done, not how.

doTitleScreen() is a function I'm working on right now. doTitleScreen() calls a a bunch of other things that when taken in the context of "I'm doing your title screen for you boss" makes perfect sense. doTitleScreen() comes almost immediately after doIntro(). Already, you know exactly what my program is doing. doIntro() calls fadeLogo(LOGO_PRODUCEDBY) and imageText("blahblahblah",x,y), again, obvious what's happening.

Sure, it gets a bit more nuts&bolts when you delve deeper but honestly, worrying about whether to call a function CreateLayer or LayerCreate, time wasting! Who gives a flip, so long as you're consistent?

Anyway, I hope you're doing zsLoadResource(GFX_LEVEL1) or similar, so that you know, just from reading that one line, what resource you're loading.

Otherwise, you need to change it to zsGetLevelOneGFX() or zsGetGFX(LEVEL1).

I've got a render_menu() which gets called with things like MENU_MAIN, MENU_OPTIONS, MENU_VISUALS etc. So much nicer to read than

select menu%
case 1
mytext("1. Play Game",50,50)
mytext("2. Exit",50,70)
case 2
mytext("1. really exit",50,50)
end select

I think Frank Taylor might express a little opinion on naming conventions if he happens by this thread ;)

*EDIT* One thing, document your functions. The first few lines of any function (except really stupid small ones) should be a description of what it does, what it expects as input, what globals it relies on and what the output is.

Far as I'm concerned, this is non-negotiable :)

I definately like the second way better. You can read it without thinking Yoda.

in blitz+

I always create something of an object using a single bank, a single bank with all variables in it.

bla=CreateNAME(args)
updateNAME(bla)
evNAME(bla) ; for the events related to Name
GetNAMEvariablename(bla)
SetNAMEvariablename(bla,value)
FreeNAME(bla)

Mainly I try to stick to the convention from blitz+ itself. Haven't enough experience with bmax/methods to see what I'm going to use for names..

Thinking Yoda :) I like that.

The thing is, Brits and Yanks say "The Red Hat". Froggies and other Europeans say "The Hat Red". So, the definition of backwards-ness really depends on your native language :)

Personally, I think "The Hat Red" is a better way. First describe the object, then tell me about that object.

I don't speak Engrish ;]

More german the backwards thing, they even stick the verb on the end of the statement.

Anyway I plump for the first option evey time in Blitz Plus i.e. ObjectCreate, ObjectMove etc. Think about OO in Bltiz Max, you wouldn't have functions you'd have Object.Create Object.Move so it's the closest to that and I been programming OO as a job for 9 years so that's what I'm used to.

I tend to prefer noun_verb(). It might be due to the fact that I used alphabetically sorted function lists for a number of years and that kept "class"-related functions grouped. Now that I no longer sort my function lists, I still prefer noun_verb(); I like to know what class I'm calling before I know what activity is being performed.

If I'm creating a fully encapsulated module (e.g. a GUI lib or a quad GFX lib) I'll usually prefix the module name on all functions, globals, and types. e.g. GFX_quad_create()

EDIT: /agree with Grey Alien's rationale.

Like Grey Alien said, OO methods are called Object.Method(), so it makes sense to use the same naming convension with non-OO functions. I was creating a Link List like structure in C once, and my functions were like this:

ListNew()
ListFree()
ListAdd()
ListRemove()

If it was C++ you would do it like:

List.Add()
List.Remove()

(the New and Free would be constructor and destructor). Basically I like naming identifiers of all types left to right like this:

General -> Specific

Items in a name get more specific as you go left to right, so it works well with the way humans read as well as OOP.

Well, as I still use the default IDE which lists funstions alphabetically, I tend to use the noun_verb() convention. That way all my functions are listed by functionality (loop_game,loop_frontend,loop_this,loop_that etc.) which makes navigating large projects much easier. No more spending five minutes trying to locate a particular function in the list.

I hate trying to find functions but most of the time I just use Find and type the name in as my conventions mean it's easy to find.

Seems like most people wouldn't be too opposed to me sticking with how I initially have named things then, which is the first option. I was a bit worried about it since commands in blitz seems to do it like the second option.

So I think that I will be sticking with the first option and then if those who gets my module complains too much about it, then I'll consider changing it around.

You could just write wrapper functions:

Function zsCreateSprite(blah)
  zsSpriteCreate(blah)
End Function

:P