Feature request: Provide a way to alter the standard naming convention for the functions

[vladipus]

I gotta say, that I still can't get used to (remember) what does what according to the currently chosen naming style. _clean and _clear are almost indistinguishable for me (and confusing to the user). The _get VS _get_at behavior is also hard to remember which is which and not at all mnemonic and more like magical.

I understand you have to provide the backward-compatibility, but perhaps a custom naming scheme solution could be implemented? As far as I can tell the function names are just parameters to some other macros, so perhaps, some additional OPLIST-like macro could be defined (even globally would do) that could redefine some of those default namings?

[vladipus]

I'm now testing the following solution, and it seems to work out. First of all I add the following macros to m-core.h:

/***************************************************************/
/********************* Global Naming Macros ********************/
/***************************************************************/

#ifndef M_NAMING_CLEAN
#define M_NAMING_CLEAN _clean
#endif

#ifndef M_NAMING_GET
#define M_NAMING_GET _get
#endif

#ifndef M_NAMING_GET_AT
#define M_NAMING_GET_AT _get_at
#endif

#ifndef M_NAMING_EMPTY_P
#define M_NAMING_EMPTY_P _empty_p
#endif

#ifndef M_NAMING_INIT
#define M_NAMING_INIT _init
#endif

#ifndef M_NAMING_CLEAR
#define M_NAMING_CLEAR _clear
#endif

Then I just replaced the corresponding occurrences in the m-array.h file to use those macros. In the result I can now use the following code which is more descriptive (at least for my own taste):

#define M_NAMING_CLEAN _clear
#define M_NAMING_CLEAR _fin
#define M_NAMING_GET_AT _ensure
#define M_NAMING_GET _at
#define M_NAMING_EMPTY_P _is_empty

#include "gt/mlib/m-array.h"

ARRAY_DEF(ints, int)

TEST_CASE("test trivial array")
{
    ints_t arr;
    ints_init(arr);
    int i = *ints_at(arr, 1);
    if (ints_is_empty(arr))
    {
        *ints_ensure(arr, 2) = i;
    }
    ints_fin(arr);
}

[vladipus]

Provided an implementation in https://github.com/P-p-H-d/mlib/pull/73 Currently a work in progress.

[vladipus]

Phew! I'm almost done on that one. I'm also auditing the code, correcting formatting, typos, misspellings and learning a lot! The library is just fantastic! I'll make sure everything works as expected, run all the tests and double-checking the final result.

[P-p-H-d]

I am not sure I want to implement such mechanism. It will go against a standardization of such library: every user of the library will use different naming, and it will be come harder to change project and use the library (or audit the code). It will also prevent including two different libraries that uses M*LIB in their public header that use different naming.

For clarification of the current naming,

• _clear is used by a lot of library to destroy object (See https://gmplib.org or https://mpfr.org )
• _clean / _clear: the first one describes more the content, rather than _clear that describes the state of a thing.
• the suffix p is a shortname for predicate (See https://en.wikipedia.org/wiki/Predication(computer_architecture) )
• _get_at: I haven't found a better naming thus.

I can see the needs of creating synonym of the basic functions however. Something like this might be a better candidate:

SYNONYM_DEF(base, MY_ARRAY_OPLIST, (CLEAN(_do_clear), CLEAR(_fin), GET_SET_AT(_ensure), GET(_at), EMPTY(_is_empty))) could create a set of functions based on the provided naming convention, and calls the real functions.

[vladipus]

• There are many projects using an either scheme. I think you've definitely have chosen not the most popular one. From my 10+ years of coding, this is the first time I have seen a bool getter to be defined as _p, for example.
• The _clean is very vague, since cleaning is not always emptying something, but usually making an object (or objects) garbage- or dirt-free. But the most serious (and error-prone) issue with it, is that it differs with _clear in only one single letter! It is also quite hard to read the code quickly having two of those so similar-looking functions. Clearing and finalization (as its usually called in IT) are also different things.
• I just can't explain to my end-user why a trivial is_empty is always empty_p, as most of the time it's not even used as a predicate at all (depending on what you call a predicate though).
• The usual getting semantic is that it doesn't change things at all, it only "gets" them, or "ensuring" those things exist in a lazy manner. The magical combination of get and at is very hard to remember as doing something different.

That might be a fine solution for user-defined entities only, I'm just not satisfied with "standard" components like strings also having those pesky _p suffixes and _clears, etc.

[vladipus]

I have now completed my renaming initiative. You are free to check it for yourself. If you don't think it's important, I'm fine with that, but, please, consider its actual practical usage as your library becomes even more flexible for all sorts of naming conventions used (and there are really many of those). Being a header-only lib, you'll hardly meet it anyways but embedded in other projects. As of me, I don't really have a choice as the project's naming scheme is already defined for the most part and I really don't want to ditch your masterpiece. =)

[vladipus]

I have now managed to solve all of the issues (including Codacy): https://github.com/P-p-H-d/mlib/pull/73 The only strange thing is with an _init function, that I had to define with a separate clause on top of the header files. Still it should be safe for everything else.

[stefantalpalaru]

It will go against a standardization of such library

The "_t" suffix is reserved by POSIX: https://www.gnu.org/software/libc/manual/html_node/Reserved-Names.html

[P-p-H-d]

You can already define your own types without the _t suffix, if you want, by using the _DEF_AS macros instead of the _DEF ones.

[P-p-H-d]

You can alter the naming convention like this:

#define M_F(a,b) M_OVERRIDE_F(a,b)
#define M_OVERRIDE__clear() , _cleanup
#include "m-core.h"