function and typedef naming thoughts

[Richard Levitte]

On Tue, 05 Mar 2019 10:11:06 +0100,
Tim Hudson wrote:
> Looking at PR#8287 I think we need to get some naming schemes written down and documented and
> followed consistently. The naming used in this PR seems to be somewhat inconsistent.
> 
> For me, I think the naming convention most often used is 
> 
> return_type SOMETHING_whatever(SOMETHING *,...)

Not always.

> as a general rule for how we are naming things. There are lots of exceptions to this in the code
> base - but this is also pretty much consistent.
> 
> And we use typedef names in all capitals for what we expect users to work with.
> We avoid the use of pure lowercase in naming functions or typedefs that are in the public API that
> we expect users to work with - all lowercase means this is "internal" only usage.
> 
> And we reserve OSSL and OPENSSL as prefixes that we feel are safe to place all new names under.

I think we need to think about this not just in terms of copying the
type of the first parameter into the function name, but also in terms
of meaning.

Even though C isn't an object oriented language, it's perfectly
possible to implement a limited class concept.  And we do this, all
over the place.  That's where function signatures such as what you
give an example of comes in, at least when looking at coding patterns
we've used for quite a while.

So, when I see a function signature like this:

    return_type OSSL_SOMETHING_whatever(OSSL_SOMETHING *, ...)

I view that as the "method" 'whatever' for the "class" OSSL_SOMETHING,
and that first parameter is that method's |this| (which must be passed
explicitely since this is C).

However, this doesn't mean to me that every function that just happens
to have OSSL_SOMETHING* as first parameters is necessarily a "method"
for that "class", it might as well be a global function that just
happens to use that "class" (and will typically call that "class"'
"methods" to get the job done).

I do understand the need for namespaces, I'm not trying to argue
against that, but I see OSSL_ and OPENSSL_ as our namespaces for new
functionality, and things like OSSL_SOMETHING_ as the prefix used to
indicate the SOMETHING "class" in the OSSL namespace.

While we're on the subject of namespaces, we are currently introducing
a number of functions that are meant to be core functions (not class
methods).  Looking at include/openssl/crypto.h, it seems like the
CRYPTO_ prefix was mainly used for core functionality (CRYPTO_malloc()
is an example).  However, I can't see myself adding to the CRYPTO_ set
for core functionality, and therefore used the OSSL_ prefix instead.

As for PR#8287, the pattern I followed is consistent with what I just
wrote:

- there is a "class", OSSL_PROVIDER.  For the public, it's entirely
  opaque, i.e. its methods are internal only, all described in
  doc/internal/man3/ossl_provider_new.pod (and all with the prefix
  ossl_provider_, i.e. the provider "class" in the ossl namespace).
  In those methods, the first parameter is normally (not always)
  OSSL_PROVIDER*, and is the natural |this| for those methods.

- there are some core functions, all described in
  doc/man3/OSSL_PROVIDER.pod.  They also take an OSSL_PROVIDER*
  parameter, but it's not their |this|.  They just pass that pointer
  along to the internal ossl_provider_ functions.

Cheers,
Richard

-- 
Richard Levitte         levitte at openssl.org
OpenSSL Project         http://www.openssl.org/~levitte/