Why does HLML not have namespaces?

[dangmoody]

Disclaimer: As always, if anyone wants to put a convincing argument forward in opposition to my views then I'll happily read it.

So this question comes up every once in a while.

The main argument being that it could potentially avoid conflicts with other codebases defining types with the same name as those present inside HLML.

I have a few problems with namespaces in general, but the main problems I have with them for HLML specifically are as follows (in no particular order):

Intended usage

I could be wrong here, and this might come across as presumptuous and possibly arrogant (forgive me if that's true; I wasn't trying to be so), but I like to think I have a valid point here:

I feel like people know what to expect with a math library. It comes with some vector, quaternion, and matrix types. You get your dot product implementation and the other usual functions. Most of them nowadays come as a series of just header files. Programmers typically download a math library with a pretty solid pre-existing idea of how they're going to use it. Therefore, I don't think a namespace is really all that necessary in that particular instance.

For other libraries (particularly in C++) this is perhaps less obvious. With less of an idea of what you expect things to be called a namespace sounds like a sensible (ish) way of separating names of symbols between codebases.

In that case I would probably still favour just prefixing every struct/class with something. If you get the prefix right then it still means less typing than having a namespace (but I suppose I would say that as a C programmer...)

Increased friction

I find that writing the following code:

float3 right = cross( up, forward );

Is significantly easier than writing the following:

hlml::float3 right = hlml::cross( up, forward );

It also reads a lot better too.

I get that you could just do the following:

using namespace hlml;

float3 right = cross( up, forward );

But then in the case of conflicting types that still wouldn't solve the problem since a symbol with the same name is present across two different namespaces/codebases/whatever, so the manual namespace identifier becomes necessary which means we end up having to prefix everything with hlml:: again. This means that it basically made no difference as to whether or not the types were encapsulated in a namespace because the names can still conflict. I understand that the point of namespaces is a means by which to mitigate this, but I personally don't consider the increased typing a worthy trade. Especially in the context of a math library where you're going to be writing the type names a lot.

I specifically chose to name things after HLSL because writing maths in a shader is very straightforward (9 times out of 10) and I find HLSL's syntax much more intuitive than GLSL's syntax. So polluting that with namespace identifiers, I think, would mar the low friction experience that I myself get as a user of HLML.

The generator could technically support it, but...

I could be being stupid here, but the only way I realistically see HLML supporting a namespace as optional (as stated in the question originally) is something like the following:

#if HLML_NAMESPACE
namespace hlml
{
#endif

struct float2
{
	// code etc.
};

#if HLML_NAMESPACE
}
#endif

I don't hate this, but I'm currently not 100% sure that I wouldn't mind staring at that every time I opened the header for a vector or a matrix type.

If I have to read through bits of boilerplate every time I open a file then I consider that friction, which, again, I want to avoid as much as possible.

In the C API I have to read through the whole extern "C" { thing every time, but there's no avoiding that one.

Brief consideration of the C API

Some C++ libraries I've come across have a C++ API as well as a C API. Out of those libraries where the C++ API has a namespace the types in the C API are typically prefixed with something to mimic the namespace (which obviously you don't get in C).

Given my previous point about intended usage: If the C++ API has a namespace but the C API doesn't; is it then expected to have prefixed names? Something similar? Something different? Nothing at all? At least with not including a namespace the lack of anything in the C API becomes a familiarity and a consistency, which I think has a net-positive impact on the usability of HLML overall.

Another option

Another option (which is its own separate discussion) is the idea of release the HLML generator as a standalone thing. What I could then do is give people the option to generate versions of the library with various options (add a namespace, prefix type names, only generate vectors/matrices of a certain type, etc.)

I often think about doing this and I think it could be good? But I'm also quite liking the simplicity of making the generator just a very deterministic tool that only does one thing at the moment.

So those are my reasons

As always, if anyone wants to put a convincing argument forward in opposition to my views then I'll happily read it.

[fstrugar]

Hey! I agree that not having namespace is cleaner.. but! there's always this odd file in your library (as it happens, I have two) where there's a collision with another library and then it's really, really nice to have a way to distinguish between the "cross" from your library or another one.

I mean, if that is not needed, and as an alternative to '#if HLML_NAMESPACE' approach, as you said yourself, you can completely "neutralize" any downsides of a namespace by just adding "using namespace hlml;", and you're back to the nice clean synthax, no? and in a place where there's collision you can either not use "using" or specify the full namespace to distinguish between the two :)

[dangmoody]

I saw in the xxHash documentation the other day that they have a #define for optional namespaces. So that tells me that this is doable, actually.

I'll look into it.

[dangmoody]

Hey @fstrugar I made an experimental release candidate for a version of HLML that has optional namespaces. Feel free to try it out if you like:

hlml_v2.3.0_RC0.zip

If this all works well I'll release it ASAP since we also have an issue where STL now has a definition for lerp which clashes with HLML, so I need to give HLML a namespace anyway.