gbadev.org forum archive

This is a read-only mirror of the content originally found on forum.gbadev.org (now offline), salvaged from Wayback machine copies. A new forum can be found here.

Coding > Naming Related Functions

#121907 - sgeos - Thu Mar 15, 2007 4:32 pm

Does anyone have a cute set of names to cover the following set of related functions? The last three can all be generically described as "operate on a list" and this is giving me trouble.
Code:
return_t opSingle  (op_t *pOp, buffer_t *pBuffer);
   // one operation

return_t opList    (op_t *pOp, buffer_t *pBuffer);
   // while (NULL != buffer) another operation

return_t opMultiple(op_t *pOp, buffer_t *pBuffer, int pCount);
   // for (i < pCount) another operation

return_t opSafe    (op_t *pOp, buffer_t *pBuffer, int pCount);
   // while (NULL != buffer) && (i < pCount) another operation

-Brendan

#121917 - gmiller - Thu Mar 15, 2007 6:13 pm

This suggestion might be too simplistic but I have a set of generic link list routines in C that manipulate list. The are llist_add, llist_insert ... and so on if that works. Not all that OO but they work on any type link list as long as they are declared correctly.

#121921 - sajiimori - Thu Mar 15, 2007 6:47 pm

Give the safe version the simplest name. The unsafe version can be named "fast", with documentation describing the tradeoff. Be safe by default.

The C library often puts an 'n' in the names of functions that take a maximum size, such as snprintf.

For something that takes a list and only uses the first element of the list, put "first" in the name... or just pass the first element.

#121953 - sgeos - Thu Mar 15, 2007 10:57 pm

sajiimori wrote:
Give the safe version the simplest name. The unsafe version can be named "fast", with documentation describing the tradeoff. Be safe by default.

Thanks for the advice. This strikes me as correct.

Quote:
For something that takes a list and only uses the first element of the list, put "first" in the name... or just pass the first element.

It is actually the base operation; it operates on a single struct, not a list.

I think I'm looking at something like this:
Code:
return_t op(op_t *pOp, buffer_t *pBuffer)
{
  // operate on a single struct
  // this routine is called by the following routines
}

return_t opList(op_t *pOp, buffer_t *pBuffer, int pCount)
{
  // operate until the end of the list
  // will stop after pCount items to prevent buffer overflow
}

return_t opListN(op_t *pOp, buffer_t *pBuffer, int pCount)
{
  // operate on a set number of items
  // do not check for the end of the list
  // good for fixed arrays
  // fastest routine
}

return_t opListFast(op_t *pOp, buffer_t *pBuffer)
{
  // operate until the end of the list
  // good for variable length arrays
  // will read past the end of the intended buffer if
  // the data does not have a terminating item
}

-Brendan