Naming conventions

[Tomas Mraz]

On Fri, 2020-06-19 at 01:48 +1000, Tim Hudson wrote:
> We have a convention that we mostly follow. Adding new stuff with
> variations in the convention offers no benefit without also adjusting
> the rest of the API. Inconsistencies really do not assist any
> developer.
> 
> Where APIs have been added that don't follow the conventions they
> should be changed. 
> 
> It really is that simple - each developer may have a different set of
> personal preferences and if we simply allow any two people to pick
> their own API pattern effectively at whim we end up with a real mess
> over time.
> 
> This example is a clear cut case where we should fix the unnecessary
> variation in the pattern. It serves no benefit whatsoever to have
> such a mix of API patterns. 
> 
> We do have some variations that we should adjust - and for APIs that
> have been in official releases dropping in backwards compatibility
> macros is appropriate.
> 
> The argument that we aren't completely consistent is specious - it is
> saying because we have a few mistakes that have slipped through the
> cracks we have open season on API patterns. 
> 
> It also would not hurt to have an automated check of API deviations
> on commits to catch such things in future. 

The problem is that there is not really fully consistent convention
followed currently (even in 1.1.1, not counting the API additions in
3.0).

For example if we would like to follow the convention _fully_ we would
have to rename these new EVP_MAC functions:

int EVP_MAC_init(EVP_MAC_CTX *ctx);
      
int EVP_MAC_update(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
 
int EVP_MAC_final(EVP_MAC_CTX *ctx, unsigned char *out, size_t *outl, size_t outsize);

to something like:

int EVP_MacInit(EVP_MAC_CTX *ctx);
      
int EVP_MacUpdate(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
 
int EVP_MacFinal(EVP_MAC_CTX *ctx, unsigned char *out, size_t *outl, size_t outsize);

or at least

int EVP_MACInit(EVP_MAC_CTX *ctx);
      
int EVP_MACUpdate(EVP_MAC_CTX *ctx, const unsigned char *data, size_t datalen);
 
int EVP_MACFinal(EVP_MAC_CTX *ctx, unsigned char *out, size_t *outl, size_t outsize);

Should we do that? I hope for the sheer ugliness of the supposedly
consistent names that we do not.

Fortunately or unfortunately depending on personal opinons we have
already diverged from that pattern with EVP_PKEY API.

And I actually hope we could add at least non-CamelCase aliases to the
existing (non-deprecated) CamelCase functions because they were always
the worst offender of the API consistency.

-- 
Tomáš Mráz
No matter how far down the wrong road you've gone, turn back.
                                              Turkish proverb
[You'll know whether the road is wrong if you carefully listen to your
conscience.]